Odoo How-To

How to Import Data in Odoo

A complete guide to importing records into Odoo using the built-in import wizard — covering CSV and Excel formats, field mapping, error handling, and best practices for large data sets.

iWesabe Editorial TeamOctober 9, 20229 min read

The Odoo import wizard allows you to create or update records in bulk from a CSV or Excel file — without writing code or running SQL. It is the standard tool for initial data migration (customers, products, opening balances) and for ongoing bulk updates (price lists, inventory counts, employee records).

This guide covers every step of the import process: preparing your file, downloading the field template, mapping columns, handling relational (many2one) fields, resolving validation errors, and managing large imports. A version notes section at the end identifies what changed across Odoo 16–19 and what to verify when a new version ships.

Opening the Import Wizard

The import wizard is available on all standard Odoo models that support bulk creation: Contacts (res.partner), Products (product.template / product.product), Sales Orders (sale.order), Journal Entries (account.move), Employees (hr.employee), and most others. Models marked as read-only or system models do not expose the import option.

Preparing Your Import File

The fastest way to get the correct column headers is to download the Odoo field template directly from the import wizard — it generates a CSV with every available field name in the correct technical format. Never guess column names manually for a large import.

  1. Open the import wizard for the target model.
  2. Click "Download a Sample File" (Odoo 19) or "Import Template for Customers" / the equivalent label for your model. This downloads a CSV with all field names as column headers.
  3. Open the CSV in Excel or LibreOffice Calc. Delete columns you do not need — fewer columns means fewer mapping errors.
  4. Fill in your data rows. Ensure the first row contains the column headers exactly as downloaded — do not rename them unless you intend to re-map manually.
  5. Save as CSV (UTF-8 encoding) or keep as XLSX — both are accepted by the Odoo 18/19 import wizard.
Odoo Import — File Format Rules
RuleDetailCommon mistake
EncodingUTF-8 required for CSV files. Excel XLSX handles encoding internally.Saving CSV from Windows Excel in ANSI encoding breaks Arabic, French, and special characters.
Date formatISO 8601: YYYY-MM-DD (e.g. 2026-06-18). Odoo also accepts DD/MM/YYYY if configured, but ISO is safer.Using MM/DD/YYYY causes day/month transposition for dates 1–12.
Boolean fieldsUse 1 or True for checked; 0 or False for unchecked.Using Yes/No or نعم/لا causes validation failure.
Many2one (relational) fieldsUse the record's name or external ID — not the database integer ID.Pasting the numeric database ID (e.g. 42) instead of the display name causes "record not found" errors.
Many2many fieldsSeparate multiple values with a comma inside the cell: "Tag A,Tag B,Tag C".Using a semicolon as separator fails; separate cells for each value fail.
Numeric fieldsUse a period as the decimal separator: 1234.56. Do not use thousand separators (commas).1,234.56 is read as the string "1" followed by an error on "234.56".

Running the Import — Step by Step

  1. From the import wizard screen, click Upload File and select your CSV or XLSX.
  2. Odoo reads the first row as column headers and attempts to auto-map them to model fields. Review the mapping panel — correctly mapped columns show the Odoo field name; unmapped columns show a yellow warning.
  3. For any unmapped column, click the dropdown next to it and select the correct Odoo field. If you downloaded the field template in step 2 of the previous section, all columns should auto-map.
  4. Click Test Import. Odoo validates all rows without writing to the database and shows row-level errors with the column and reason.
  5. Fix all errors in your source file and re-upload, or fix them directly in the wizard's inline editor if there are only a few.
  6. When Test Import shows zero errors, click Import. Odoo creates (or updates) all records in a single database transaction — if any row fails, the entire import rolls back.

Importing Many2one (Relational) Fields

Many2one fields link a record to a single related record — for example, a contact's `country_id` links to a `res.country` record. The import wizard accepts three lookup methods for many2one fields:

Many2one Field — Three Lookup Methods
MethodColumn header syntaxExample valueWhen to use
Name lookupfield_name (plain — e.g. "Country")Saudi ArabiaEasiest. Works when the display name is unique. Fails if two records have the same name.
External ID lookupfield_name/id (e.g. "Country/External ID")base.saMost reliable for standard Odoo data. External IDs are stable across instances. Use for countries, states, product categories.
Database ID lookupfield_name/.id (e.g. "Country/.id")187Avoid for migrations — database IDs differ between Odoo instances. Only use for exports re-imported into the same database.

Common Import Errors and How to Fix Them

Odoo Import Error Reference
Error messageRoot causeFix
"No matching record found for [value] in field [field]"A many2one lookup could not find a record with that name or external IDCheck spelling and case. Export the related model to get the exact name or external ID values to use.
"Invalid date format" or "Cannot convert value to date"Date cell is not in YYYY-MM-DD format, or is stored as a number (common in Excel)Format the date column as Text in Excel before filling it, then use YYYY-MM-DD. Alternatively use the TEXT() formula: =TEXT(A2,"YYYY-MM-DD").
"The field [field] is required but was not provided"A mandatory field column is missing from the file, or the cell value is emptyCheck which fields are required for the model (marked with a red asterisk in the Odoo form view). Add the column and ensure every row has a value.
"Duplicates found" or import creates duplicate recordsNo external ID column — Odoo cannot match incoming rows to existing records and creates new onesExport the existing records to get their external IDs, then add an `id` column to your import file. Odoo will update instead of create.
Import wizard is greyed out or the Import button is not visibleThe current user does not have write access to the model, or developer mode is required for the modelCheck user access rights (Settings → Users & Companies → Users → Access Rights). Some technical models require developer mode.

Best Practices for Large Data Imports

  • Split large files into batches of 2,000–5,000 rows. Very large single imports (50,000+ rows) can time out or consume excessive memory on shared Odoo.sh or cloud instances.
  • Always run Test Import before clicking Import. A failed import rolls back entirely — testing first saves time.
  • Import reference data (countries, product categories, UoM) before transaction data (sale orders, invoices). Odoo resolves many2one lookups at import time — missing reference records cause row failures.
  • Schedule large imports during off-peak hours (nights/weekends) on production systems — the database lock during import can slow concurrent user operations.
  • For initial migrations over 100,000 records, use Odoo's `base_import` module via RPC or the `odoo-import-export` community module — both bypass the wizard's row limit and support chunked commits.

Version Notes and Spot-Check Guide

Odoo Import Wizard — Changes by Version
Odoo versionImport wizard locationFile formatsNotable change
Odoo 16Action menu (⚙) → Import Records on list viewsCSV, XLSXUI refresh; inline error editor added for small corrections without re-uploading
Odoo 17Action menu (⚙) → Import RecordsCSV, XLSXNo functional changes to the import wizard
Odoo 18Action menu (⚙) → Import RecordsCSV, XLSXNo functional changes. "Download a Sample File" label confirmed.
Odoo 19Action menu (⚙) → Import RecordsCSV, XLSXNo functional changes. Verified June 2026.

Migrating data to Odoo from another system?

iWesabe handles complete data migration projects — from Tally, QuickBooks, SAP, or legacy spreadsheets — including data cleansing, mapping, and go-live validation.

Discuss Your MigrationWhatsApp

Frequently Asked Questions

What file formats does Odoo import support?
Odoo 18 and 19 accept CSV (comma-separated, UTF-8 encoded) and Excel XLSX files. XLS (older Excel format) is not supported — convert to XLSX first. JSON and XML imports are not available through the UI wizard; they require RPC or custom code.
How do I update existing records through the Odoo import wizard?
Include an `id` column in your CSV file containing the external ID of each record you want to update. Export the records first (Action → Export) to get their external IDs in the format `__export__.model_name_`. When Odoo finds a matching `id` value, it updates that record instead of creating a new one.
What is the maximum number of rows I can import at once in Odoo?
There is no hard-coded row limit in the Odoo import wizard, but practical limits exist based on your server's memory and timeout settings. On Odoo.sh or shared cloud plans, imports above 10,000–20,000 rows often time out. Best practice is to split large files into batches of 2,000–5,000 rows. For migrations over 100,000 records, use RPC-based bulk import tools.
How do I import a product with multiple variants in Odoo?
Import product variants through the `product.product` model (not `product.template`). Each variant is a separate row. You need columns for the template fields (name, category) plus the attribute value columns. It is easier to first create the product template manually with its attributes, then import the variant-level data (prices, internal references, barcodes) via the product.product import.
Why does my import say "no matching record" for a field that exists in Odoo?
The most common cause is a case or spacing mismatch between your CSV value and the record's name in Odoo. Export the reference records (e.g. countries, categories) to get the exact names as stored in your Odoo instance, then use those exact strings in your import file. Avoid copying display names from the web UI — they may differ from the stored `name` field value.
Can I import data into Odoo without developer mode?
Yes — for all standard models (contacts, products, sales orders, employees, etc.), the import wizard is available to users with write access without needing developer mode. Developer mode is only required for importing into technical/system models (e.g. ir.model, ir.rule) or when you need to see the model's technical field names in the column mapping panel.
iWesabe Editorial Team

iWesabe Editorial Team

Practitioner insights on Odoo ERP, ZATCA compliance, and Saudi enterprise digital operations — written by iWesabe's consulting, finance, and engineering teams.

About iWesabe

Related Articles

Migration

Migrating from Tally or QuickBooks to Odoo ERP in Saudi Arabia

How KSA SMEs replace standalone accounting with a full Odoo stack — chart of accounts mapping, VAT/ZATCA continuity, parallel-run validation, and a cutover that doesn't break March's filing.

Odoo Development

Custom Paper Format in Odoo QWeb Reports

How to create, configure, and bind custom paper formats to Odoo QWeb reports — covering UI setup, XML override, margin control, and header/footer sizing.

Odoo ERP Guide

What Is Odoo ERP? The Complete Guide to Odoo (Formerly OpenERP) for Saudi Businesses

From TinyERP to OpenERP to Odoo 19 — how the platform evolved and why 12 million+ businesses run on it today

Explore Related Solutions

Financial Management

Automate your Saudi Arabia accounting — ZATCA Phase 2 e-invoicing, VAT returns, Zakat provisioning, multi-currency bank reconciliation, and real-time financial reporting — all inside one connected Odoo platform. Fully localised for KSA and the GCC by iWesabe.

Explore

CRM & Customer Relationship Management

Turn every lead into a closed deal. Odoo CRM gives your sales team a structured Kanban pipeline, automated follow-up sequences, and a 360° customer view — all connected natively to Accounting, Inventory, and Email Marketing.

Explore

Manufacturing Management ERP

Run lean, traceable production with Odoo Manufacturing — work orders, Bills of Materials, quality control, and real-time OEE dashboards built for KSA factory floors.

Explore

Supply Chain Management

From purchase order to final delivery — Odoo Supply Chain connects procurement, multi-warehouse inventory, demand forecasting, and vendor management into one real-time platform. Purpose-configured for Saudi Arabia and the GCC by iWesabe.

Explore
View All Products