Importing data into Dolibarr from a CSV or Excel file

Dolibarr can take your customers, contacts, products, stock or purchase prices from a spreadsheet, through a four-step wizard. Be aware that it writes straight into the tables: it does not do everything the input screens do (no stock movement, no price history), and it is strict about file formats.

This guide follows the Dolibarr 24.0.2 wizard with real CSV and Excel files, imported on 14 October 2026 on a test instance, including about twenty errors caused on purpose to record the exact messages.

Where the wizard is

Menu Tools › Imports / Exports › New Import. If the menu is missing, enable the Data imports module in Home › Setup › Modules/Applications.

The wizard has four tabs:

1. Step 1: the dataset to import (third parties, products…). Only datasets of enabled modules are listed: enable Products, Stocks or Vendors first if you need them.
2. Step 2: the file, added with Add file, then selected with the arrow on the right.
3. Step 3: the matching between the file’s columns and Dolibarr’s fields.
4. Step 4: the options, then Run Import Simulation, and finally Import Data.

The most used datasets, with their exact label in step 1:

What about bank statements?

The Dolibarr 24.0.2 wizard does not import them. With the Banks module enabled, the only bank-related dataset is the third parties’ bank details: there is no dataset for the lines of a statement. Importing a statement therefore needs development work or an add-on module; we have tested none.

The order to follow

A file often points to records created by another one: a contact gives the name of its third party, a stock line gives the product reference and the warehouse reference. If that record does not exist yet, the line is rejected. Hence the order we followed, without errors:

1. third parties;
2. contacts;
3. products;
4. warehouses;
5. stock;
6. vendor prices;
7. categories.

Start from the template file

In step 2, Dolibarr offers Download a sample file, as CSV or Excel. The file contains:

• a header line in your language, with the field code in brackets: Third-party name* (s.nom), Country code (s.fk_pays)… The asterisk marks mandatory fields;
• a second, example line describing what is expected (0 (closed) / 1 (active), etc.).

The CSV uses a comma as separator and UTF-8 encoding.

Keep the headers as they are. In step 3, Dolibarr recognises the code in brackets (or a label identical to its own, such as City) and fills in the matching by itself: in our test, the 14 columns of a third-party file were matched without touching anything, including a custom attribute. With your own headers (“Company name”, “Is customer”), everything has to be matched by hand.

Then delete the example line and the columns you do not need, and fill in your data. The header line is not a problem: in step 4, Limit range (From - To) starts at 2 by default.

Step by step, with a third-party file

Step 2. The file must not exceed Dolibarr’s upload limit, 2,048 KB after a fresh install (the tooltip next to the button shows it). Above that, adding the file fails with “Error, failed to save file.”. The limit is changed in Home › Setup › Security, Files tab (see our Docker install guide, which details this setting).

Step 3. First check the CSV format options line: the Field Separator must be the one of your file (see below, it is the first cause of failure). Then check each drop-down list. Below the table, a note says either “All target fields that need a mandatory value are mapped”, or “Some mandatory target fields are not mapped” followed by their names.

That note is only a warning: the import still goes through. In our test, a third party imported without the Customer* and Vendor* columns was created as neither customer nor vendor. Read it.

Step 4. Three settings: the lines to import, the Key (column) for update (see below) and the Import mode. Then Run Import Simulation.

The simulation really runs the import, then cancels it: nothing stays in the database (we counted the third parties before and after). If all is well, it shows “Result of simulation: No error” and the number of lines that will be inserted and updated. Otherwise it lists the errors line by line, and the Import Data button is greyed out: “You must correct all errors before running the definitive import.”

It is all or nothing: a single line in error blocks the whole file. Fix the file, add it again and run the simulation again.

The import. Import Data shows the number of inserted and updated lines, and an import number (for example 20261014131140), stored in the import_key field of every record created or modified. Write it down: the wizard has no button to undo an import, and this number lets you find, in the database, what it wrote. Make a backup before a large import: Back up and restore Dolibarr.

For the next file, start again from New Import. In our test, going straight back to step 2 to pick another file made Dolibarr reapply the previous file’s matching, with absurd errors as a result.

New in 24: the import mode

Dolibarr 24 adds an Import mode in step 4:

• Secured mode (slower), the default: for each line, Dolibarr triggers the automatic actions an on-screen entry would. With the Agenda module, our import of 5 third parties created 5 “Third party … created” events, and an update created “Third party … modified” events;
• Fast mode (faster): no automatic action line by line. Our import of 2 third parties in this mode created no event.

The simulation never triggers these actions. Keep the secured mode, except for a very large file for which you want neither events nor notifications.

Updating records instead of creating them

Without a key, every line creates a record. Importing the same file again therefore creates duplicates: in our test, the 5 third parties were created a second time (and those whose customer code was auto got a new code).

To modify existing records, choose a Key (column) for update in step 4. For each line, Dolibarr looks for a record with the same value:

• one record found: it is updated;
• none: the line creates a new record (in our test, 2 third parties updated, 1 created);
• several: an error, which reads in the language files “Multiple records have been found with these filters: …” (seen on screen in French with ThirdPartyName = ‘Atelier Wendling’).

The keys offered depend on the dataset: for third parties, Third-party name, Zip Code, Email, Customer Code, Vendor Code, the accounting codes and the professional IDs; for products, the Ref.; for stock, the Product and the Warehouse. Pick a unique value, such as the customer code, a company registration number or the reference: a name can exist twice.

Two precautions, both checked:

• Every matched column is rewritten, including empty cells. We updated a third party’s phone with a file whose Email column was empty: its email address was erased. Columns absent from the file are left alone (the “Secteur” custom attribute stayed in place). For an update, put only the key and the columns to change in the file.
• The key column must be matched and filled in, otherwise the simulation answers “You request to search duplicates on field nom but no value was provided for this field on this line.”

If an import has already created duplicate third parties or contacts, our Duplicate finder module finds them and offers to merge them.

Common errors, with the exact message

The separator

Dolibarr starts from the comma. If the first line contains no comma but more than two semicolons, it switches to the semicolon by itself. Checked consequence: a semicolon file with three columns or fewer (typically a stock file) is not recognised, and everything lands in a single column.

The fix: in step 3, type ; in Field Separator, click Update, then redo the matching, which Dolibarr has emptied (or left incomplete). For a tab-separated file, type \t. The default is set in the module’s configuration (gear icon of Data imports): “Csv character separator (By default)”.

Another case: in a comma file, an address such as “Zone artisanale, bâtiment B” without quotes shifts all the following columns. The message then only shows the consequence: “Field H: ‘Strasbourg’ is not a value found in field code of Countries”.

A telltale sign: “Result of simulation: No error” with “Number of lines that will be inserted: 0”. No column is matched.

The encoding

Save the CSV as UTF-8. We imported a file encoded in Windows-1252: accented letters came through (“Hôtel à l’Étoile”), but the € sign, “œ”, the curly apostrophe ’ and the dash – turned into invisible characters. “Société Œnologique d’Alsace” became “Société nologique dAlsace”, with no error in the simulation. A UTF-8 file with a BOM (an invisible mark at the start of the file) went through without a problem, as did an ISO-8859-1 file without those characters.

Dates

Format YYYY-MM-DD. A date in another format is rejected:

Field G: '14/10/2026' does not match regex rule ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]( [0-9][0-9]:[0-9][0-9]:[0-9][0-9])?$

“Field G” means column G of your file.

Numbers

Decimal point, no space: 12.50. In a product price, 12,50 is rejected with “Data truncated for column ‘price’ at row 1”. Some fields convert the comma (a third party’s capital: 12 500,50 became 12500.5), others do not: do not rely on it.

Mandatory fields and coded values

The expected values:

• Customer: 0 (neither customer nor prospect), 1 (customer), 2 (prospect), 3 (customer and prospect); Vendor: 0 or 1; Status: 1 (active) or 0 (closed);
• Country code: the ISO code, FR, DE, GB;
• a contact’s title: the dictionary code, MR, MME, MLE, MTRE or DR;
• Customer Code or Vendor Code: auto to let Dolibarr assign the next number (our third parties got CU2610-00001, CU2610-00002… with the default numbering). Empty cell or no column: no code at all.

Records referred to by name or reference

A contact is linked to its third party by the third party’s exact name. A typo gives “Field A: ‘Boulangerie Kiefer’ is not a Third party existing ref”. A name present twice (a duplicate) gives, according to the language files, “Several record found when searching from ref … No way to know which ID to use.”

A reference made only of digits is read as an internal ID. Our product with reference 1001 (internal ID 9) could not receive stock: Dolibarr was looking for product no. 1001, hence “Cannot add or update a child row: a foreign key constraint fails”. Writing ref:1001 in the column solved it. According to the code, the rule applies to every column that points to another record (product, third party, warehouse, category).

Custom attributes

Custom attributes (extrafields) appear as columns at the end of the list, under their label: Secteur (extra.secteur) in the template file. In our test, they were imported with the third parties, with no particular setting.

Excel files (.xlsx)

The wizard reads the Excel 2007 format (.xlsx) directly. With a file saved by LibreOffice, we found that:

• a formula is read as such, not its result: “Incorrect double value: ‘=1.5*2’ for column … price”. Replace formulas with their values before importing;
• a date cell arrives as 2026-10-01 00:00:00: accepted for a third party’s creation date, rejected for a product’s (the rule there does not allow a time). Put dates as text, in YYYY-MM-DD format;
• a postcode entered as a number loses its leading zero: 06000 became 6000. Format the column as text.

According to the code, only the workbook’s active sheet is read.

Products: the price incl. tax and the history do not follow

The import writes the price as it is, without recalculating it:

• with only a Selling price (excl. tax) (1.20), the price incl. tax stays at 0 in the database and the price history is empty. In our test, only opening the product’s Selling prices tab recalculated the price incl. tax and created the first history line (opening the product card or the product list changed nothing); a product whose tab nobody opens keeps a price incl. tax of 0;
• with both the excl. and incl. tax columns, both values are stored as they are: it is up to you to keep them consistent;
• updating a price by import (Ref. key) changed the price excl. tax (1.201.50), but the price incl. tax stayed at 1.44 and the history did not move. To change a few prices, use the product’s Selling prices tab.

The PriceBaseType* column is mandatory: HT (excl. tax) or TTC (incl. tax).

Stock: quantities, not movements

The Stocks and location (warehouse) of products dataset writes the quantity per warehouse directly. In our test, 40 notebooks in Strasbourg and 15 in Colmar: the product shows 55 in stock, but “Latest movement: None”, the movement list is empty, and the weighted average price is not calculated.

Importing the same product into the same warehouse again fails (“Duplicate entry ‘6-3’ for key ‘uk_product_stock’”); with both keys Product and Warehouse, the quantity is replaced (200180), not added.

For opening stock you want to keep a trace of, use an inventory, which creates real movements: see Entering opening stock.

Categories: the list imports, the links do not (24.0.2)

The List of tags/categories dataset works. The Type is 0 for products, 1 for vendors, 2 for customers/prospects (the template file gives the full list). For the parent category, put 0 for a top-level category: left empty, the line is rejected (“Column ‘fk_parent’ cannot be null”). A sub-category can point to its parent by its label, even one created higher up in the same file.

However, in 24.0.2, links between categories and records cannot be imported. We tested products, customers and vendors: the simulation shows “Dolibarr has detected a technical error” and rejects every line, even with correct values. The cause is in the check the wizard performs (a malformed query); the code is identical in the 24.0 branch on 14/10/2026.

The tested workaround: in the product list, tick the products, choose the Assign a Tag action, select the category, then Validate: “2 record(s) modified”. The third-party list offers the same action (not tested here).

One last trap: import profiles

In step 3, the wizard lets you save the matching as an import profile, to reuse it. Saving works, but in 24.0.2 choosing the profile and clicking Apply changes nothing: the lists stay empty (the form sends step 3, whereas the code only handles the profile in step 4). Headers taken from the template file do the same job, and they work.

Summary

• Start from the template file and keep its headers: the matching happens by itself.
• Import in this order: third parties, contacts, products, warehouses, stock, vendor prices, categories.
• CSV in UTF-8, dates as YYYY-MM-DD, numbers with a point, no formulas.
• Semicolon file with three columns or fewer: type ; yourself in step 3.
• Read the simulation: a single error blocks the whole file.
• To modify records, a unique key and only the columns to change: an empty cell erases.
• Stock and prices: the import creates neither movements nor history; check the price incl. tax.
• Categories: link them with the list’s mass action, not by import, in 24.0.2.

If an import still refuses to go through, the €90 diagnosis is about looking at your instance and your file with you for one hour, then giving you in writing what blocks it and what fixing it would cost.