How to Use Salesforce Data Loader (Step-by-Step)

If you need to load more than 50,000 records into Salesforce — or you need to update records based on an external ID — Data Loader is the tool. The web-based Data Import Wizard handles the small stuff; Data Loader handles everything else.

This is the practical guide. Install, configure, and execute the four most common operations without breaking your org.

Estimated read time: 10 minutes

What is Salesforce Data Loader?

Data Loader is a Salesforce-built desktop application that bulk-imports, exports, and modifies Salesforce data. Available for Windows and macOS. Free.

It supports up to 5 million records per operation, all standard and custom objects, and uses the Bulk API by default for performance.

When to use Data Loader vs Data Import Wizard

Need	Use
Import < 50K records, basic mapping	Data Import Wizard (in-browser)
Import > 50K records	Data Loader
Upsert based on external ID	Data Loader
Delete records	Data Loader
Hard delete (skip recycle bin)	Data Loader
Custom object on a complex schema	Data Loader
Scheduled, recurring loads	Data Loader CLI

If you're a Salesforce admin doing weekly data work, install Data Loader.

Installation

1. From Setup, search Data Loader → click Open Data Loader Download Page
2. Choose the right installer for your OS
3. Run the installer (macOS users: you'll need to allow it in System Settings → Security)
4. Launch Data Loader

For macOS, the installer also installs Java if you don't have it. Don't skip this step.

First-time configuration

Open Data Loader → Settings → Settings:

• Use Bulk API: Check this. Faster for any meaningful volume.
• Enable serial mode for Bulk API: Only check if you're hitting locking errors. Slower.
• Insert null values: Check if you want blank cells in your CSV to clear field values. Otherwise blanks are ignored.
• Time Zone: Set to your org's time zone to avoid date-shifting surprises.

Save settings. You only need to do this once per machine.

Operation 1: Insert (create new records)

Use when adding new records that don't exist yet.

1. Click Insert
2. Log in to your org (production or sandbox)
3. Select the object (e.g., Contact)
4. Browse to your CSV file
5. Click Create or Edit a Map → drag CSV columns to Salesforce fields. Save the map.
6. Click Next → choose where to save success and error files (always set this)
7. Click Finish

Data Loader processes the file. When done, you get two output files:

• success.csv — records that were inserted, with their new Salesforce IDs
• error.csv — records that failed, with the error message per row

Review the error file. Always.

Operation 2: Update (modify existing records)

Same flow as Insert, but click Update instead. Your CSV must include the Salesforce Id column for each record you're updating.

If you don't have the Salesforce Ids, use Export first to get them.

Operation 3: Upsert (insert or update based on external ID)

Upsert is the most powerful operation. It uses an External ID field on the Salesforce object to decide:

• If a matching record exists → update it
• If no match → create a new one

Setup requirements:

• The Salesforce object must have a custom field marked External ID and Unique
• Your CSV must include that external ID column

Use case: you maintain a system of record outside Salesforce (e.g., your data warehouse) with stable IDs. Upsert lets you sync without worrying about whether each row is new or existing.

Operation 4: Delete

Click Delete. CSV must include the Salesforce Id column. Records go to the recycle bin (recoverable for 15 days).

For permanent deletion: click Hard Delete. Records bypass the recycle bin. Cannot be recovered. Requires "Bulk API Hard Delete" permission.

The 7 safety habits that prevent disasters

1. Test in a sandbox first. Always. Even for "simple" loads.
2. Save success and error files to a known folder. Don't lose them.
3. Run a small batch first. 100 records before 100,000.
4. Use upsert with an external ID when possible — safer than separate insert + update.
5. Disable triggers and validation rules for one-time loads only when necessary, and re-enable immediately after.
6. Don't truncate dates. Excel loves to convert "2026-01-15" to "1/15/26" and back to "1/15/2126." Format the column as Text in Excel before saving.
7. Always export your data first if you're about to update or delete. That CSV is your rollback plan.

Common errors and fixes

• "INVALID_CROSS_REFERENCE_KEY" — you're referencing a related record (like Account or Owner) by an Id that doesn't exist. Verify the lookup IDs.
• "INVALID_FIELD_FOR_INSERT_UPDATE" — you're trying to set a field that's read-only or formula. Remove from the mapping.
• "FIELD_CUSTOM_VALIDATION_EXCEPTION" — a validation rule fired. Fix the data or temporarily deactivate the rule.
• "REQUIRED_FIELD_MISSING" — a required field is blank in your CSV. Fill it or default it.
• "ENTITY_IS_LOCKED" — concurrent process is touching the same record. Use serial mode or retry.

Want migration done for you?

Most data loads are simple in concept and complicated in execution. Format issues, validation rule conflicts, lookup mappings, post-load reconciliation — it adds up.

RevKit's Data Migration packages handle it end to end:

• Single-object load (up to 100K records): $499
• Multi-object migration with relationship resolution: $1,499
• Full system migration with mapping and reconciliation: from $4,999

Get Data Migration →

Related reading

• Salesforce Migration Checklist: What Actually Needs to Be Done
• Salesforce Duplicate Records: The Complete Cleanup Guide
• The Data Governance Framework Your Salesforce Needs