The Definitive Guide to Migrating to Dolibarr

Dolibarr ERP CRM is an open-source PHP/MySQL business suite released under GPL, originally authored by Laurent Destailleur in 2003 and now governed by the Dolibarr Foundation with an active French-led international community ¹. The same code base ships ERP, CRM, billing, accounting, inventory, manufacturing, POS, HR and project modules — every feature is a module the administrator toggles on or off.

The typical Dolibarr customer is a small or mid-sized business — 1 to 200 employees — that wants ERP, invoicing and basic CRM without the licence cost of Odoo Enterprise, Acumatica or Microsoft Dynamics. Compared with Odoo, Dolibarr positions on a flatter learning curve, no compulsory subscription and lower hardware demands; compared with ERPNext, it positions on a much shallower PHP/MySQL stack that any LAMP-fluent administrator can self-host.

The shapes of migration that actually land on Dolibarr fall into four patterns. First, spreadsheet exits: a business graduating from Excel and Access books into a single relational database that can issue compliant invoices. Second, legacy ERP replacements — Sage 50, EBP, Ciel, QuickBooks Desktop or aging Odoo 8/10 installs — where licence renewal triggers a re-platform.

Third, multi-tool consolidation, where a small business runs a separate billing tool, CRM, stock tool and shared mailbox, and wants one system. Fourth, open-source migrations between FOSS stacks — usually from ERPNext, Odoo Community or a custom PHP app — where the project is really a re-architecture against Dolibarr's module map. A QuickBooks exit has clean third-party and product parity but messy account numbering; an Odoo migration has rich automation that does not move across.

What makes migrating *to* Dolibarr easier than the category average is the Module Imports tool, which accepts CSV and Excel against predefined datasets for every standard object and runs a dry-run *simulator* before any row is written to the database ². Direct MySQL/MariaDB access is also legitimate — practitioners routinely script the llx_* tables when the import module is too slow ³.

What makes it harder than the average is the module-toggle architecture: until a module is enabled, its tables, menus and import datasets do not exist, which means import order is dictated by module activation order, not data dependency alone. The platform also relies on the Extra fields system for any custom data, which behaves differently from native fields during import and is easy to forget when sizing the project.

Workflows, scheduled jobs, ECM document trees and accounting binding rules do not import — they are rebuilt from documentation. Teams that scope for that work up front finish on time; teams that assume parity with a commercial ERP do not.

Until a module is enabled, its tables, menus and import datasets do not exist — import order in Dolibarr is dictated by module activation, not data dependency alone.

Dolibarr's data model is a set of business objects backed by the llx_* MySQL tables — llx_societe for third parties, llx_product for products, llx_facture for customer invoices, and so on. Each object has a small set of native fields and an optional Extra fields layer for custom data ³. Modules turn on additional objects; until you enable the Stock module, for example, llx_entrepot and llx_product_stock are not part of your effective schema.

Before you map a field on the source side, you need to know which destination object the row belongs on, which module owns it, what fields are required, and which value will serve as your match key on re-import. The table below summarises the objects you will touch in a Dolibarr ERP migration.

Third parties use the code_client and code_fournisseur properties as your two natural business keys — these can be auto-generated or supplied by the import ⁵. Products use ref as the canonical reference. Invoices use ref (the document number) plus the third-party link.

For deterministic re-runs, every import dataset exposes an import_key column you populate with a value of your choice — usually a batch identifier or the source primary key. The import_key is stored alongside the record and is what lets you bulk-roll-back a specific import without affecting other data ⁵. Plan to use it on day one of the project.

When you import, the Dolibarr import module operates in Insert or Insert-or-Update mode against the chosen dataset ². Insert-or-Update needs a column flagged as the update key on each row. Direct SQL imports bypass the module entirely and demand that you handle constraints, triggers and entity (multi-company) values yourself. Custom data lives in the Extra fields system — the catalogue below covers the types you can model and the limits to plan around.

Relationships in Dolibarr are modelled as foreign-key columns on the child object plus, for some pairings, an llx_element_element link table that records contextual associations between two arbitrary objects. Third parties support an explicit parent / child hierarchy on parent for company groups and branches ⁷, and contacts attach to third parties through llx_socpeople.

There is no native master-detail cascade-delete; deleting a third party leaves its invoices intact (and indeed Dolibarr blocks the delete if any non-draft document references it). The platform also supports multi-entity (multiple legal companies on one install) — every llx_* table has an entity column, and any import script that ignores it will silently load rows into entity 1 ⁸.

The single best predictor of a clean Dolibarr migration is how much work you do on the source side before the first CSV is selected in the import wizard. Practitioners on the Dolibarr forum consistently report that import failures trace to source-side data issues — bad date formats, missing dictionary codes, decimal commas instead of points — far more often than to bugs in the importer ¹⁰²².

The single best predictor of a clean Dolibarr migration is how much work you do before the first CSV hits the import wizard.

Treat the source export as raw material that needs to be shaped to Dolibarr's expected formats — dates rewritten to YYYY-MM-DD, numerics with point decimal separators (not European commas), country codes resolved to Dolibarr's llx_c_country rowid or ISO code, currencies normalised to the entity's base currency or to a column the multi-currency module recognises ²²³⁰.

Source-side prep

• Audit and dedup the source database before export — duplicate third parties are the single most common post-import cleanup. Use exact-email and fuzzy name+address matching, and resolve before exporting.
• Normalise dates and numerics — Dolibarr's import expects ISO dates and dot-decimal numerics. European comma decimals are silently truncated in some stock movement flows and break amounts in others ²².
• Map source dictionary values to Dolibarr dictionaries — payment terms, payment modes, countries, languages, VAT rates and units of measure all live in llx_c_* dictionaries. Either match by code or pre-insert any missing rows ⁸.
• Stamp a stable external ID on every record in the source export and plan to load it into the import_key column so re-runs and reconciliation are deterministic ⁵.
• Decide what is in scope for historical documents. Invoices and orders can be imported with their original dates, but every line counts as a row and Dolibarr's accounting binding has to run after the load if you want them in the GL.

Destination-side prep

• Spin up a staging Dolibarr instance that mirrors production — DoliCloud trial, a Docker container, or a DoliWamp install on a workstation. A staging instance is non-negotiable for a dry-run ⁹.
• Enable every module you intend to use before importing — Stock, Product Lots, BOM, Manufacturing Orders, Multi-currency, Double-entry Accounting. The module's tables and import datasets only appear after activation.
• Pre-create users, groups and permissions under Users & Groups → Permissions — owner assignment fails silently if a referenced user does not exist, and triggers tied to permissions will misfire ⁶.
• Define every Extra field on the right object with the right type — Setup → Dictionaries → Extra fields. Adding fields later forces a second import pass per row.
• Set up the chart of accounts, fiscal year, journals and VAT rates in the Accounting module before any invoice load — invoices imported against an empty CoA cannot be bound and you will have to re-run the binding job after.

People prep

Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours for a small business, longer for a multi-entity ERP — and communicate it to every department that touches invoicing, stock or purchasing. Train accounting on the journal binding flow, sales on the quote-to-invoice pipeline, and warehouse staff on the Stock movement screen before go-live. A typical SMB migration runs four to eight weeks of elapsed time including audit, mapping, dry-run and acceptance.

Dolibarr exposes several load paths and the right one depends on dataset size, object mix, and whether you need to re-run idempotently. The Module Imports wizard covers most one-shot SMB migrations. The PHP CRUD classes handle programmatic, repeatable loads. Direct MySQL INSERT is legitimate and common when the wizard is too slow. Third-party tools sit on top and add staging or warehouse-first patterns.

Module Imports wizard

The native importer lives under Home → Tools → New import, with the Imports module enabled by default on most installs ². The wizard walks five steps: choose a predefined dataset (Third parties, Products, Customer invoices, Supplier invoices, Stock movements, etc.), pick CSV or Excel as the format, upload the source file, map each source column to a target field, then run the simulator that validates the load without writing to the database ²¹⁴.

Limits are infrastructure-driven, not licence-driven. The hard ceiling is PHP's upload_max_filesize, post_max_size, memory_limit and max_execution_time plus MySQL's max_allowed_packet and wait_timeout. Defaults are around 2 MB upload and 128 MB memory; large loads need 64 MB upload and 512 MB-plus memory in php.ini ²¹. The wizard is comfortable up to roughly 20,000 to 50,000 rows per object on a tuned LAMP host before the user runs out of patience.

PHP CRUD classes

The PHP CRUD classes (Societe, Product, Facture) are available to anyone writing a script directly on the Dolibarr server: they call fetch(), mutate the object, then call create() or update() and run all business triggers correctly ³. This is the safe programmatic path because it runs the same business-rule validation as the UI.

The throughput ceiling is your PHP-FPM worker count and MySQL connection pool, not any platform-imposed limit. For loads above a few tens of thousands of records, parallelise across multiple worker processes against a tuned PHP-FPM pool and respect max_input_vars.

Direct MySQL / MariaDB SQL

Direct database access is the fast path for very large loads. The official wiki explicitly endorses it: "Direct database access to read the data" is listed as one of the three legitimate methods on the Mass imports page ³. The cost is that you bypass all business triggers — accounting binding, stock movement side effects, document number generation — so you must reproduce those steps yourself or run the matching reconcile scripts after the bulk load.

Third-party staging tools

Airbyte ships a Dolibarr connector; LibreOffice can write directly to the Dolibarr MySQL database via its built-in database front-end, a pattern documented on the Dolibarr wiki ³. For larger projects, teams adopt a warehouse-first pattern: source data lands in PostgreSQL or BigQuery via Airbyte/Fivetran, gets transformed in SQL, then the cleaned tables drive either the PHP CRUD classes or a direct MySQL load against llx_*.

Mapping is where every ERP migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether trial balance ties on day two, whether stock reports match the warehouse on day five, and whether your accountant trusts the books on day thirty.

Work object by object, top to bottom of the import order: dictionaries first (countries, currencies, VAT, payment terms), then chart of accounts and fiscal year, then third parties, then products and stock, then open AP/AR, then GL opening balances, then historical documents if any.

Third parties (customers and suppliers)

Chart of accounts (CoA) and GL opening balances

Dolibarr ships several chart-of-accounts templates — French PCG, Belgian PCMN, Spanish PGC, a generic English template and others — installed via Accounting → Setup → Chart of accounts. Pick the template that matches your fiscal jurisdiction *before* you import anything that posts to the GL. The CoA lives in llx_accounting_account and is keyed on account_number (the natural account code), so your import file maps source account → Dolibarr account_number directly.

Opening balances are posted as a single journal entry on the fiscal year's opening date, debiting and crediting the right balance-sheet accounts so that trial balance equals the source on day one. The cleanest mechanism is the Manual journal entries screen (or a programmatic load against the AccountingJournal and AccountingEntry classes), with one balanced batch per fiscal year you carry forward. Do not import opening balances as customer or supplier invoices — those will inflate AR/AP aging and double-count revenue.

Open AR and AP — customer and supplier invoices

Open invoices migrate as Dolibarr customer invoices (Facture) and supplier invoices (FactureFournisseur) in draft → validated state with original issue and due dates. Each invoice imports as a header plus line rows. The trick is the ref column: invoices use auto-numbering by default, but you usually want to preserve the source document number — set the module's number mask to allow free-form references, or stamp the original number into ref_customer and let Dolibarr generate a fresh ref.

For partial-paid invoices, import the invoice with its full original amount, then post a payment for the already-collected portion against the invoice so the residual matches the source aging report exactly. Do not adjust the invoice line amounts to reflect the residual — that breaks VAT and revenue reconciliation.

Products, services, units of measure and lots

Stock-on-hand does not import directly into a quantity column — Dolibarr derives current stock by summing llx_stock_mouvement rows. The supported path is to enable the Stock module, create your warehouses, then post a single *Stock Correction* movement per product per warehouse to seed quantities to the cutover number. For product lots / batches and serial numbers, enable the Product Lots module first and stamp lot or serial onto the movement rows themselves.

European users repeatedly warn about decimal comma vs point: stock corrections accept fractional quantities for some products but silently round to integer on others, depending on UoM and Dolibarr version, and any value entered with a comma is ignored — the validation passes but no movement is written ²⁸.

Bills of Materials and Manufacturing Orders

If manufacturing is in scope, enable the BOM and Manufacturing Orders modules. A Bill of Materials is a header row (parent product, quantity, UoM) plus child component lines (component, quantity per parent, UoM). Import BOM headers first, capture the resulting rowid, then load component lines with fk_bom populated. Manufacturing Orders consume BOMs and post stock movements automatically — do not import historical MOs as discrete records; recreate open ones and let Dolibarr post the movements ²⁹.

Multi-currency, exchange rates and historical FX

Multi-currency is a separate module that must be enabled before any document references a non-base currency ³⁰. Once enabled, each third party can have a default currency, and each invoice carries multicurrency_code, multicurrency_tx (the rate at document date) and multicurrency_total_ht. For historical invoices migrated mid-year, store the original rate on each row — Dolibarr does not back-fill historical FX from any rate provider, so leaving the rate column empty defaults to today's rate and silently misstates revenue.

Fiscal year and period close

Define the fiscal year under Accounting → Setup → Fiscal year before posting any journal entries. Closed periods block posting for that range, so the sequence is: open the new fiscal year, load opening balances dated to the opening date, load open AR/AP at original dates, run the binding job to push invoices into the journal, then close prior years. Do not close before validation finishes — re-opening is a manual llx_accounting_fiscalyear UPDATE.

Historical activities, ECM documents and attachments

Events and the Agenda do not have a published bulk-import dataset; the practitioner pattern is a direct insert into llx_actioncomm against the source object's rowid ¹⁰. Documents and attachments live on the Dolibarr server's /documents/ directory tree, organised by object type. Inline upload via CSV is not supported — write a script that places files under the right subfolder and inserts an llx_ecm_files row. Per-file size is gated by upload_max_filesize, often raised to 50–100 MB ³¹.

Audit trail, ownership and original timestamps

Standard datec (creation date) and tms (modification timestamp) on most llx_* tables are writable from import datasets and from programmatic loads, so original dates *can* be preserved — unlike many SaaS ERPs. The fk_user_author / fk_user_modif columns hold creator and modifier user IDs; pre-provision the matching users so historical ownership lands correctly. If a referenced user does not exist at import time, the row lands with NULL ownership — fine for queries but it breaks reports that filter by user.

Validation is the bridge between the import finishing and users being allowed in. Practitioners running Dolibarr migrations consistently recommend a three-stage validation: a test load of 10 percent of records with stakeholder spot-checks, the full load with monitoring of row counts and journal totals, and a 30-day post-migration audit cycle. The most reliable signal is having the accountant and the warehouse lead verify their own data — they spot wrong totals faster than any reconciliation script.

Build a reconciliation queries spreadsheet that compares source and destination on the counts below. Anything outside a 0.1 percent variance on financial totals gets investigated before users get login access; a stricter bar than for CRMs because the GL has to balance to the penny.

• Total third parties imported vs source — split by customer-only, supplier-only and both, since the client / fournisseur flags must match.
• Total products imported vs source — and a checksum of cost prices and selling prices summed across the catalogue.
• Stock-on-hand per warehouse per product vs source — query SUM(value) FROM llx_stock_mouvement grouped by warehouse and product, and compare against the source inventory snapshot.
• Open AR and AP per third party — sum of unpaid invoice residuals from llx_facture and llx_facture_fourn, compared against the source aging report.
• Trial balance per account — sum of debits and credits per account_number in llx_accounting_bookkeeping, compared against the source trial balance for the cutover date.
• Document count per type per fiscal year — invoices, supplier invoices, orders, proposals — to catch range gaps caused by the document-number mask.
• Extra field population rate — count NULLs per extra field per object; an unexpectedly high NULL rate means a column was dropped during wizard mapping.

On top of reconciliation, run a manual spot-check protocol: pick 30 random records across objects and verify each field against the source UI. Pick five high-value invoices and trace the full graph — third party, lines, payments, journal entries. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by import_key.

Dolibarr does not ship a native bulk-undo. The real rollback strategy is: take a mysqldump of the entire database and a tar of the /documents/ tree before the import starts, stamp every imported row with an import_key column containing the batch identifier, and if catastrophe strikes, bulk-delete by that key (DELETE FROM llx_<table> WHERE import_key = 'batch-2026-05-27') and re-import from the cleaned source.

Cutover sequencing: (1) source goes read-only and the team is notified; (2) final delta export captures everything that changed during the test-import window; (3) delta is imported into staging, then production; (4) reconciliation runs against the live database; (5) users get login access and a 48-hour hyper-care window with the migration lead on call; (6) source decommission is scheduled for 30 to 90 days out, never the same day.

Dolibarr does not certify partners the way Salesforce or HubSpot do. Instead, the project maintains a public Preferred Partners list of consultancies and freelancers who have demonstrated production experience — NEXT GESTION, Inovea, Dolicraft, and a long tail of country-specific shops are commonly named on the official site ¹⁷. DoliCloud, run by the project's founder, offers managed hosting plus migration assistance as a paid service.

Freelancers from the Dolibarr forum are a legitimate alternative for smaller projects — many post their availability under the *Asking a freelance* section of the Mass imports wiki page ³. Expect language to skew French and Spanish on that channel; English-speaking shops cluster around Dolicraft, Atm Consulting and a handful of UK and German consultancies.

On the ETL and iPaaS side, Airbyte ships a dedicated Dolibarr source connector and is the most common choice for warehouse-first migrations ³. Fivetran and Stitch do not ship a native Dolibarr connector, so teams using them write a custom HTTP source against the platform. Workato and n8n are common picks where the migration is bundled with workflow automation. LibreOffice Base is a legitimate, documented direct-write tool for small one-off loads against the MySQL backend ³.

Managed-migration cost ranges vary widely with scope. A spreadsheet-to-Dolibarr move for an SMB of five to twenty people typically lands in the €5,000–€20,000 range, training included, per NEXT GESTION's published guidance for standard SMB scope. A multi-entity ERP replacement with historical accounting, multi-currency, manufacturing and 50,000+ products commonly runs €25,000–€80,000, with the upper end driven by document depth, custom module count and the number of integrations to rebuild.

For teams that want to outsource the migration end-to-end, FlitStack specialises in Dolibarr migrations and handles the dictionary mapping, Extra fields setup, chart-of-accounts alignment, GL opening balance posting, stock-correction seeding and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on record count and source platform, with separate line items for multi-entity scope and historical-document depth so the engagement is transparent before signature.

This is one of several legitimate paths — the right choice for any given team depends on whether they want a Dolibarr Preferred Partner, a freelancer from the forum, an Airbyte warehouse-first approach, or a specialist migration vendor. Explore FlitStack →