On this page
- What do you need before you install Data Loader?
- How do you install Data Loader on Windows or macOS?
- How do you log in to Data Loader?
- How do you insert records with Data Loader?
- How do you update, upsert or delete records?
- How do you export data from Salesforce?
- Which Data Loader settings matter most?
- How do you fix common Data Loader errors?
- How do you schedule Data Loader from the command line?
- Can an AI agent do the load for you?
- Sources
- FAQ: common questions about how to use Salesforce Data Loader
To use Salesforce Data Loader, install Java, download Data Loader and log in with OAuth. Then pick an operation, choose the object and a CSV file, map columns to fields, and click Finish. Data Loader writes a success file and an error file for every run (Salesforce Developers).
Salesforce Data Loader is a free client application for bulk import and export of data. It supports CSV files of up to 150 million records and every standard and custom object (Data Loader Guide). Not sure it is the right tool? Read Data Loader vs Data Import Wizard first.
Clientell AI, the AI Salesforce admin, checks a CSV for duplicates and bad values before you load it. See the Salesforce data cleaning use case.
What do you need before you install Data Loader?
You need three things: a supported edition, the right permissions and Java. Data Loader is available in Enterprise, Performance, Unlimited and Developer editions. It needs Java Runtime Environment (JRE) version 17 or later (Download and Install Data Loader).
Your user needs API Enabled plus the object permission for each operation:
Swipe sideways to see all columns
| Operation | Permission on the object | Extra permission |
|---|---|---|
| Insert | Create | API Enabled |
| Update | Edit | API Enabled |
| Upsert | Create or Edit | API Enabled |
| Delete | Delete | API Enabled |
| Hard delete | Delete | Bulk API Hard Delete |
| Export and Export All | Read | API Enabled |
| Source | Insert, Update, or Delete Data | Bulk API Hard Delete help |
The standard System Administrator profile does not include Bulk API Hard Delete. Add it through a permission set (Salesforce Help).
How do you install Data Loader on Windows or macOS?
Follow these steps from the Data Loader Guide:
- Install a JRE, version 17 or later, that matches your operating system and chip. Azul Zulu and Eclipse Temurin both work.
- Download Data Loader from the Salesforce Developers tools page.
- Optional: check the file is signed by Salesforce with
jarsigner -verify dataloader_v<version>.zip. - Extract the zip file.
- Run
install.baton Windows orinstall.commandon macOS. - If macOS blocks the installer, open System Settings > Privacy & Security and click Open Anyway.
- Pick an install folder and answer the prompts.
Open Data Loader from the desktop icon, the Start menu or the Applications folder. Salesforce updates Data Loader every release, and its major version number matches the current API version (Salesforce Developers).
How do you log in to Data Loader?
Click any operation, such as Insert, and the login screen opens. You have two choices.
- OAuth (sign-in through your browser, with no password stored in Data Loader). Pick the environment, Production or Sandbox, and sign in through the browser. This is the simplest path and needs no security token.
- Password. Enter your username, then your password with your security token added to the end, with no space.
If login fails with "Failed to send request", check Settings > Settings. The Server host should read https://login.salesforce.com, or https://test.salesforce.com for a sandbox. Data Loader connects on HTTPS port 443, so ask your network team to allow it (Salesforce Help).
How do you insert records with Data Loader?
This example loads new accounts from accounts.csv with columns Name, Industry and Phone.
- Click Insert and log in.
- Select the object, here Account (Account), then browse to
accounts.csv. Click Next. - Data Loader counts the rows. Click OK.
- Click Create or Edit a Map, then Auto-Match Fields to Columns. Drag any unmatched column onto its field.
- Click Save Mapping to keep the map as an
.sdlfile for the next run. Click OK, then Next. - Choose a folder for the success and error files. Click Finish, then Yes.
Expected result: the success file lists each new record with its new Salesforce ID. The error file lists each failed row with an ERROR column that says why. Fix those rows in a copy of the error file and insert only them again (Salesforce Developers).
Load parents before children. Insert Account rows first, then put their new IDs in Contact.AccountId before you insert contacts.
How do you update, upsert or delete records?
Each one uses the same wizard as insert. What changes is the CSV and the field Data Loader matches on, such as Account.Id or Account.ERP_Id__c.
- Update. The CSV needs an
Idcolumn. Export the records first to get it. - Upsert. Data Loader updates a record when it finds a match and inserts one when it does not. Match on
Idor on an external ID field, such as a customERP_Id__cfield marked External ID. - Delete. The CSV needs only the
Idcolumn. Deleted records go to the Recycle Bin. - Hard delete. Turn on Use Bulk API in Settings first. Hard-deleted records skip the Recycle Bin and cannot be recovered (Enable Bulk API).
Always export a backup before you update or delete. Export Id plus every field you will change, such as Lead.OwnerId and Lead.Status. To undo a bad update, run a second update from that file.
How do you export data from Salesforce?
- Click Export. Click Export All instead to include soft-deleted records and archived activities.
- Log in and pick the object, such as Contact.
- Name the target CSV file and click Next.
- Tick the fields and add conditions. Data Loader builds the query, for example
SELECT Id, Email, AccountId FROM Contact WHERE Email = null. - Click Finish.
Export needs only Read on the records (Export Data from Salesforce). To find records to restore, use Export All and filter on IsDeleted = TRUE.
Which Data Loader settings matter most?
Open Settings > Settings. These five decide most outcomes.
Swipe sideways to see all columns
| Setting | What it does | Default and limits |
|---|---|---|
| Batch size | Records sent per call | SOAP: up to 200, with 50 to 100 recommended. Bulk API: up to 10,000 |
| Use Bulk API / Use Bulk API 2.0 | Sends large jobs in the background | Bulk API 2.0 sets the batch size itself |
| Insert null values | Blank cells clear the field | Not available with Bulk API. Use #N/A to clear a field there |
| Export batch size | Records returned per SOAP query call | Default 500, minimum 200, maximum 2,000 |
| Assignment rule | Runs a lead or case assignment rule on load | Enter the rule ID |
| Source | Configure Data Loader | Bulk API limits |
Blank cells do not clear fields with Bulk API on. Data Loader ignores empty values on update in that mode, so the old value stays (Data Loader Behavior with Bulk API Enabled).
How do you fix common Data Loader errors?
Read the ERROR column in the error file. These codes cover most failed rows.
Swipe sideways to see all columns
| Error in the file | Usual cause | Fix |
|---|---|---|
REQUIRED_FIELD_MISSING | A required field is blank or unmapped | Map the column or fill the value |
INVALID_CROSS_REFERENCE_KEY | A lookup ID points to a record that does not exist | Load the parent first, then use its new ID |
DUPLICATE_VALUE | A unique field already holds that value | Use upsert on that field instead of insert |
FIELD_CUSTOM_VALIDATION_EXCEPTION | A validation rule blocked the row | Fix the value, or load with a user the rule allows |
UNABLE_TO_LOCK_ROW | Parallel batches hit the same parent record | Turn on serial mode with Bulk API (Enable Bulk API) |
Sort the CSV by parent ID before a large child load. Rows that share a parent then land in the same batch, which cuts lock errors.
How do you schedule Data Loader from the command line?
The command-line mode runs on Windows only (Command-Line Prerequisites). The setup has four parts:
- Create a key file and encrypt your password with
encrypt.bat. Skip this if you log in with OAuth. - Save the field map as an
.sdlfile. - Describe the job in
process-conf.xmlas aProcessRunnerbean, for exampleid="accountInsert". - Run
process.bat "C:\dataloaderconfig" accountInsertand schedule that command in Windows Task Scheduler.
Each step is in the Data Loader command-line guide. On a Mac, or for loads with no script to maintain, see our Data Loader alternatives and the Data Loader automation recipes.
Can an AI agent do the load for you?
Yes, for the parts that take judgment. You describe the job in plain words, such as "set the owner of every Banking account to Priya". Clientell AI reads your org's objects and fields, builds the change and shows you every record it will touch.
Safety first. Clientell AI reads your org in read-only mode first. It builds changes in a sandbox, tests them, and asks before it changes anything in production. Read how the AI Salesforce admin works.
Try it in Clientell AI: "Export every Contact with a blank email, then show me the fix for each one before you update." Start a 14-day trial, no card.
FAQ: common questions about how to use Salesforce Data Loader
Is Salesforce Data Loader free?
Yes. Data Loader is a free download from Salesforce for Enterprise, Performance, Unlimited and Developer editions.
Can I undo a Data Loader delete?
Yes, for a normal delete. Records stay in the Recycle Bin for 15 days (Salesforce Help). A hard delete has no undo.
Why do blank cells not clear my fields?
You have Use Bulk API turned on. Put #N/A in the cell, or turn off Bulk API and tick Insert null values.
Does Data Loader work on a Mac?
Yes. The desktop app runs on macOS with Java version 17 or later. Only the command-line batch mode needs Windows.
Do I need a security token to log in?
Not with OAuth, which signs you in through the browser. With password login, add your security token to the end of your password, with no space.
Sources
Salesforce documentation
- Data Loader Guide: introduction
- Download and Install Data Loader
- Insert, Update, or Delete Data Using Data Loader
- Export Data from Salesforce
- Configure Data Loader
- Data Loader Behavior with Bulk API Enabled
- Enable Bulk API
- How to Enable the Bulk API Hard Delete Permission
- Error "Failed to send request" in Data Loader
- How to Undo a Record Deletion
Last reviewed October 2026
Last updated: October 22, 2026




