Data Loader
Data Loader is Salesforce's free, official desktop application for loading, exporting, and transforming Salesforce records in bulk.
Definition
Data Loader is Salesforce's free, official desktop application for loading, exporting, and transforming Salesforce records in bulk. It runs on macOS and Windows, supports all the standard DML operations (insert, update, upsert, delete, hard delete, export), reads and writes CSV files, and uses Bulk API or Bulk API 2.0 under the hood for high-volume operations. Data Loader is the workhorse tool for any Salesforce admin or consultant doing data migrations, periodic loads, or one-off mass updates.
The tool has two interaction modes: an interactive GUI for ad-hoc operations and a command-line interface for scripted, scheduled workloads. The GUI walks the user through field mapping, operation type, and file selection. The CLI runs from a configuration file and works well in nightly cron jobs or post-deployment data refreshes. Data Loader authenticates via OAuth (recommended) or the deprecated username-password flow, and respects all the standard Salesforce security model: field-level security, sharing rules, validation rules, and triggers all fire as the user running the load.
How Data Loader powers Salesforce data migrations
Operations: insert, update, upsert, delete, hard delete, export
Data Loader supports all the standard Salesforce DML operations. Insert creates new records. Update modifies existing records (requires the Id column). Upsert inserts or updates based on a matching external ID field. Delete moves records to the Recycle Bin (recoverable for 15 days). Hard delete bypasses the Recycle Bin and is irreversible. Export pulls records via SOQL and writes them to CSV. Export All includes deleted and archived records, useful for migration scenarios.
Mapping CSV columns to Salesforce fields
The CSV column headers map to Salesforce field API names through a mapping file (.sdl). The Auto-Match Fields to Columns button matches headers that exactly equal the API name. Custom field API names with the __c suffix need exact case-sensitive matches. Save the mapping file and reuse it across runs to keep mappings consistent. Mapping errors are the most common Data Loader bug; double-check that every required field on the target object has a CSV column or a hardcoded default.
Batch size and Bulk API behavior
Data Loader processes records in batches. Default batch size is 200 for standard API or 10,000 for Bulk API. Smaller batches reduce per-batch impact on governor limits and locking but slow the overall load. Larger batches improve throughput but increase the chance of UNABLE_TO_LOCK_ROW errors on contentious data. Tune batch size based on the data shape: 200 for triggered objects with heavy automation, 10,000 for simple loads on objects with no triggers.
The CLI mode for scheduled and scripted loads
Beyond the GUI, Data Loader supports a CLI driven by configuration files. The process-conf.xml file declares a series of process beans, each with a name, operation, sObject, mapping file, encryption key, and CSV path. Run a process with: dataloader.exe process.bat processName. This is the standard pattern for automated nightly loads, post-deployment data refreshes, and integration jobs that need to run on a schedule. The CLI also supports encryption of credentials in the config file via the encrypt.bat utility.
Success, error, and unprocessed result files
Every Data Loader run produces three CSV files: success.csv (records that processed successfully, with the assigned Id), error.csv (records that failed, with error descriptions), and a summary log. Review the error file after every run; common errors include validation rule failures, missing required fields, foreign key resolution failures, and lock contention. The error file format makes it easy to fix and re-run only the failed records.
Authentication: OAuth and the username-password deprecation
Data Loader has supported OAuth since 2018. The Settings > Connection screen lets you authenticate via OAuth using the embedded Connected App (the default and recommended path) or a custom Connected App. The legacy username-password flow with a security token is being phased out as MFA enforcement reaches more users. New deployments should configure OAuth from the start. The Salesforce CLI also includes a data loader replacement (sf data import) that handles authentication through standard sf org credentials.
Alternatives and when Data Loader is the right tool
For one-off ad-hoc loads, Data Loader is the standard pick. For loads under 50,000 records on a simple schema, Data Import Wizard inside Salesforce is faster (no installation needed). For scheduled ETL with transformation logic, integration platforms like MuleSoft, Informatica, and Boomi handle complex pipelines that Data Loader does not. For very large volumes with custom transformation requirements, Salesforce CLI (sf data import) or direct Bulk API 2.0 integration are the modern alternatives. Data Loader sits in the middle: reliable, free, well-documented, and the right tool for most desktop-driven bulk work.
How to use Data Loader for a bulk load
Running a clean Data Loader job takes preparation more than it takes Salesforce knowledge. Validate the input CSV, plan field mapping, pick the right operation, run a test on a small subset first, then process the full load. Always run from a sandbox before production unless the operation is read-only.
- Install Data Loader from Setup
Setup > Data Loader > Download. Install the OS-appropriate version (macOS, Windows). Launch and authenticate via OAuth on first run. The embedded Connected App handles authentication for the default install.
- Prepare the CSV input
Format the CSV with one row per record, columns named to match Salesforce field API names. Include the Id column for update or delete operations. Include the external ID column for upsert. Validate the CSV opens cleanly in Excel and has no encoding issues (UTF-8 or Windows-1252).
- Choose the operation
Launch the appropriate operation: Insert, Update, Upsert, Delete, Hard Delete, Export. Each opens a wizard. Pick the target sObject, browse to the CSV file, and proceed to mapping.
- Map CSV columns to Salesforce fields
Click Create or Edit Map. Use Auto-Match Fields to Columns for exact matches. Manually map remaining columns. Save the mapping file (.sdl) for reuse. Confirm every required field on the target object has either a CSV mapping or a hardcoded default.
- Test on a small subset
Run a test load with 10-50 records first. Review the success and error files. Confirm records appear correctly in Salesforce. Fix any data or mapping issues before running the full load.
- Process the full load
Run the operation on the full CSV. Monitor progress in the Data Loader window. For very large loads, switch to Bulk API mode in Settings > Settings (enables larger batches and parallel processing).
- Review the result files
Open success.csv and error.csv. The success file includes the assigned Salesforce Ids; the error file describes per-record failures. Triage errors, fix the input data, and re-run only the failed records.
- Document the run for audit
Save the success, error, and log files to a project folder with the run date and operator. Most data migrations require audit evidence; Data Loader output files are the standard artifact.
Insert, Update, Upsert, Delete, Hard Delete, Export, Export All. Drives the entire run; pick carefully.
Records per batch. 200 default for standard API; 10,000 for Bulk API. Tune based on object automation and data shape.
Setting that switches from standard API to Bulk API for the operation. Required for loads over 50,000 records.
- CSV field mapping is case-sensitive on API names. Account_Name__c is not the same as account_name__c. Mismatched cases produce silent unmapped columns that load with NULL values.
- Hard Delete bypasses the Recycle Bin and is irreversible. Triple-check the input CSV before running a hard delete because there is no way to recover the records.
- Lock contention on master-detail data produces UNABLE_TO_LOCK_ROW errors when batches of child records target the same master. Sort the CSV by master Id before loading.
- Triggers, validation rules, and workflow rules all fire during Data Loader operations. Loads can take much longer than expected on objects with heavy automation, and rule failures show up in error.csv.
- Username-password authentication is being phased out alongside MFA enforcement. Configure OAuth before legacy authentication is blocked for the integration user.
Trust & references
Cross-checked against the following references.
- Data Loader OverviewSalesforce Help
- Install Data LoaderSalesforce Help
- Data Loader Developer GuideSalesforce Developer
Straight from the source - Salesforce's reference material on Data Loader.
- Data Loader GuideSalesforce Help
- Data Loader Command-Line InterfaceSalesforce Developer
- Data Loader OAuth AuthenticationSalesforce Help
Hands-on resources to go deeper on Data Loader.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the primary benefit of Data Loader for Salesforce administrators?
Q2. Can a Salesforce admin configure Data Loader without writing code?
Q3. In which area of Salesforce would you typically find Data Loader?
Discussion
Loading discussion…