Data Import
Bulk-loading data via CSV/XLSX is one of Frappe's strengths — used for initial migration, ongoing customer/item updates, or routine bulk operations.
The Data Import DocType
Open Data Import → New. Pick:
- DocType (e.g., Customer, Item, Sales Invoice)
- Action — Insert New Records or Update Existing Records
- Upload a CSV/XLSX file
- Map columns to fields (auto-detected when headers match field labels)
- Hit Start Import — runs in the background, you get a report when done
Template download
For a fresh import, click Download Template on the Data Import form to get a CSV with the exact column headers and field types pre-filled. Easier than guessing field names.
Child tables
For DocTypes with child tables (Sales Invoice with its items), the import format flattens them: one row per parent, repeating the parent name in subsequent rows for each child line. The template explains the convention.
Updates by name
To update existing records, include the ID column with the record name. Frappe matches and updates. Skipped rows are reported in the import log.
Validation
Each row is validated against the DocType's rules — mandatory fields, link validations, custom validate hooks. Failed rows are listed in the log with the reason; valid rows still import.
When to use the API instead
Data Import is interactive (one DocType at a time). For nightly syncs from another system, use the API — it's faster, scriptable, and avoids the desk UI overhead.
Large imports
For 100k+ rows, prefer chunked imports or direct DB scripts (run via bench --site mysite execute). The Data Import UI works but processes one record at a time, which is slow at scale.