Salesforce Data Loader: What It Is and How to Use It

Hey friends,

Sooner or later every admin gets a spreadsheet with a few thousand rows and a request that starts with "can you get these into Salesforce by Friday?" Data Loader is the tool for that job, and it also gets your data back out again.

Salesforce Data Loader is a client application you install on Windows or macOS to insert, update, upsert, delete, hard delete and export Salesforce records in bulk, using CSV files. Salesforce's own page calls it a client application for the bulk import or export of Salesforce data. You pick an operation, log in, choose the object and your CSV file, map the columns to Salesforce fields, and Data Loader writes success and error files so you can see exactly what happened.

If your job is small and simple and you'd rather not install anything, the Data Import Wizard may be enough. I compare the two in Data Import Wizard vs Data Loader. This post is the how-to for Data Loader itself: install, log in, load, update, export and read the results.

One honest note before we start: for everyday exports and small updates, I usually reach for a browser extension called Salesforce Inspector Reloaded instead of Data Loader. Data Loader is still the right tool for big or automated loads, and it's the one the Admin exam expects you to know. Further down I explain exactly when to use which.

What you can do with Data Loader

Every operation is a wizard in the same shape. These are the six you'll see on the main screen, with the permission each one needs (from the Data Loader Guide):

Mass deletes need the Modify All Data permission. When you load, Data Loader reads from a CSV file or a database connection. When you export, it gives you a CSV file back.

Before you install

• Your edition. Data Loader is available in Enterprise, Performance, Unlimited and Developer editions.
• Your permissions. You need API Enabled on your user, plus the object permission for what you're doing, such as Create on accounts to insert accounts. Hard-deleting through the Bulk API also needs the Bulk API Hard Delete permission.
• Your computer. Salesforce's download page lists Windows 10 and 11, and macOS 13, 14 and 15.
• Java. Salesforce no longer bundles Java with the Windows installer. Install a Java Runtime Environment (JRE), version 17 or later, before you install Data Loader.
• A safe place to practice. If you don't have a sandbox, a free Developer Edition org is a fine place to try your first load. Data Loader works with it, and nothing you break matters. My sandbox types guide covers the other options.

How to install Salesforce Data Loader

Salesforce updates Data Loader every release, so always download the newest version. Here are the steps from the install guide:

1. Install JRE 17 or later for your operating system. Pick a download that matches your OS and CPU architecture, and if you're unsure which version, choose the latest. Salesforce's examples are Azul Zulu and Adoptium Eclipse Temurin.
2. Set your JAVA_HOME environment variable to the folder where you installed the JRE.
3. Download the most recent version from the Data Loader page on the Salesforce developer site.
4. Open the downloaded .zip file and select Extract All.
5. In the Data Loader folder, run install.bat on Windows or installer.command on macOS.
6. Choose a folder for the installation, then answer the prompts.
7. Open Data Loader from the desktop icon, the Start menu (Windows) or your Applications folder (macOS).

On macOS 15, if the installer is blocked, open Privacy & Security, scroll to the Security section and click Open Anyway next to the blocked installer. If you ever install a newer version, Salesforce says to move config.properties from the configs folder of the old version into the new one to keep your settings.

How to log in to Data Loader

Every operation starts at the log in step. Salesforce's login notes say you can use OAuth 2.0 (Data Loader v64.0.1 and later) or a username and password. Two details save people an afternoon:

• Security token. If your org restricts IP addresses, logins from untrusted IPs are blocked until activated. Salesforce emails you a security token, and you add it to the end of your password. A password of mypassword and a token of XXXXXXXXXX becomes mypasswordXXXXXXXXXX.
• Sandboxes. To load into a sandbox, Salesforce says to change Server host in Settings to your sandbox URL, in the form https://MyDomainName--SandboxName.sandbox.my.salesforce.com. With OAuth, you select your environment on the log in screen.

Newer versions (64.0.2 and later) can connect through an external client app, which is a one-time job for an admin in Setup. The steps are in Create a Secure Connection with an External Client App.

How to insert records with Data Loader

Say you're adding new accounts. Save a CSV file with a header row that names what each column holds. Here's a small example (a real load would also carry fields like phone and billing address):

1Name,Industry
2Pine Street Co,Technology
3Harbor Works,Manufacturing

Then follow the insert wizard:

1. Start Data Loader and click Insert.
2. Log in, then click Next.
3. Choose the object, Account in this case. If it isn't in the list, select Show all objects. Objects are listed by label, with the developer name in parentheses.
4. Click Browse and pick your CSV file, then click Next. When Data Loader finishes initializing the object and file, click OK.
5. Map your columns to Salesforce fields (next section), then click Next.
6. Click Browse to pick the folder for the success and error files, then click Finish and confirm with Yes.
7. Watch the progress window. When it finishes, use View Successes or View Errors, then click OK.

Update, Upsert, Delete and Hard Delete use the same wizard. Only a few steps change, and I'll point those out below.

How to map CSV columns to Salesforce fields

The mapping dialog ties each CSV column to a Salesforce field:

• Click Auto-Match Fields to Columns to let Data Loader match columns to fields by how similar the names are. For a delete, auto-match only works on the ID field.
• Fix anything it missed by dragging a field from the Salesforce list onto the CSV column it belongs to.
• Click Save Mapping if you'll repeat this load. Next time, use Choose an Existing Map instead of rebuilding it.
• Click OK to use the mapping for this operation.

Look at the mapping before you click Finish. A column mapped to the wrong field is the most common reason a clean file loads the wrong data.

How to update records with Data Loader

Updates match on the record ID, so your file needs an ID column. Salesforce's mass update steps are short, and worth following in order:

1. Get your data by exporting the object or running a report. Make sure it includes the record ID.
2. Save an extra copy of the file as a backup.
3. Edit your working file in a CSV editor such as Excel.
4. Start Data Loader and click Update. The wizard matches on record ID.
5. Review the success and error files when it finishes.
6. If you made a mistake, use the backup file to update the records back to their previous values.

A working file for a phone number fix looks like this, with the record ID first:

1Id,Phone
2001xx000003DHP0AAO,555-0150
3001xx000003DHP1AAO,555-0151

One trap here is blank cells. According to the settings reference, when Data Loader uses the Bulk API or Bulk API 2.0, empty values are ignored when you update records. To set a field to null in that case, put #N/A in the CSV. With the default SOAP API, the Insert null values setting decides whether blanks overwrite existing data.

How to export data from Salesforce

Export is the safest operation, and the one to run first when you're unsure. Follow the export wizard:

1. Click Export. Click Export All instead if you also want archived activity records and soft-deleted records.
2. Log in and click Next, then choose the object.
3. Choose or create the CSV file to export to. If you pick an existing file, the export replaces its contents, and you confirm with Yes.
4. Click Next and build the SOQL query: choose your fields, optionally add conditions, and review the generated query. With no conditions, you get all the data you can read.
5. Click Finish and confirm with Yes. When it completes, click View Extraction to see the file.

SOQL is Salesforce's query language, and the query screen writes it for you. If you want to pull fields from a related object, use a relationship query, such as:

Select Id, LastName, Account.Name FROM Contact

Field names in relationship queries are case-sensitive, so ACCOUNT.NAME doesn't work where Account.Name does. Salesforce lists what Data Loader exports can't do: nested queries or child objects, polymorphic relationships, attachments (use the weekly export instead), and compound fields such as an address (export the individual components). My SOQL relationship queries cheat sheet goes deeper on the query side.

How to upsert and delete records

Upsert. Your file needs a column to match on, either an external ID (a custom field with the External ID attribute) or the record ID. In the wizard you choose the matching field from a dropdown. If the object has no external ID fields, ID is used. Rows that match are updated and rows that don't are created.

Delete and Hard Delete. Here is the sentence from the guide to remember: Data Loader deletes records based on the IDs in the CSV file, not the object you selected. A hard delete skips the Recycle Bin, so you cannot restore those records from it. For mass deletes, Salesforce's steps are to export the records with all fields and keep an extra copy as a backup, export them again with only the record ID, run the delete wizard mapping only the ID column, and review the success and error files.

How to read the success and error files

After each load, Data Loader writes two CSV files to the folder you chose, one starting with success and one with error (Salesforce's description). The success file lists the loaded records and adds a column with the new record IDs. The error file lists the rejected records and adds a column that says why each one failed.

• To open them inside Data Loader, choose View | View CSV. It shows 1,000 rows by default, and Open in External Program sends the file to Excel.
• Exports don't create a success file unless you turn on Generate status files for exports in Settings.
• If your object has a field named success or error, your output columns can show the wrong information. Rename the columns to avoid that.

My habit is to fix the rows in the error file and load only those again, rather than rerunning the whole file.

Data Loader settings worth knowing

Open Settings | Settings to change how Data Loader behaves. The full list is in the configuration guide. These are the ones I'd check first:

For how the bulk options differ under the hood, see my Bulk API 2.0 guide.

Common Data Loader mistakes

• Deleting from the wrong file. The IDs in the CSV decide what gets deleted. Export the IDs, open the file and check it before you run the delete.
• Updating with no backup. Save a copy of the export first. It is your only way back.
• Expecting blanks to clear a field. They don't with the Bulk API. Use #N/A.
• Loading in the wrong org. The login screen and Server host decide where your data lands. Check them before a big load, especially if you also use a sandbox.
• One giant file that times out. If you get a timeout error, Salesforce says to split the file into smaller files and try again. Check the results first, because part of a failed load may have succeeded.
• No Java. If Data Loader won't install or start, check that JRE 17 or later is installed and JAVA_HOME points to it.

Salesforce Inspector Reloaded: the quicker way to do everyday imports and exports

Data Loader earns its place in this post because it's the standard tool and it handles volume. But most of the data jobs I do are small: pull some records with a query, fix a column, and push the change back. For that, a browser extension is quicker. There's no Java and no desktop app to start, and you stay in the browser where you're already logged in to Salesforce.

Which Inspector do I mean? There are two projects with nearly the same name. The original Salesforce Inspector was built by Søren Krabbe. Salesforce Inspector Reloaded is the continuation maintained by Thomas Prouvot, and it's the one I mean here. Thomas explains on the Salesforce Developers Blog that the original repository had gone stale, so he released Reloaded on the Chrome Web Store in March 2023. Its official pages are the documentation site and the GitHub repository.

What it does well for everyday work:

• Queries and exports in the browser. The Data Export page lets you write SOQL, keep several queries open in tabs, filter the results by column and export them as CSV or Excel.
• Paste-in imports. The Data Import page accepts pasted CSV, JSON or Excel data, can detect the object from an Id column, greys out the columns it won't load, and supports undelete.
• Import options. You can set the assignment rule, duplicate rule and owner change options for an import.
• More than data. The same extension has shortcuts to Setup, a Show all data view of a record, org limits and a REST explorer. I only cover import and export here.

How to install Salesforce Inspector Reloaded

1. Install it from your browser's store: Chrome Web Store, Firefox Browser Add-ons or Edge Add-ons. Check that the developer is Thomas Prouvot, so you don't install the original or a look-alike.
2. Log in to your Salesforce org the usual way.
3. Open the extension from your browser toolbar while you're on a Salesforce page. Its popup is where you reach Data Export and Data Import.
4. If it stops working, check two things from the official how-to and README. If you just turned on My Domain, restart your browser. If your org has API Access Control enabled, your admin has to set up access for the extension first.

What to know before you install it:

• It is not an official Salesforce product. Salesforce says that development and support aren't Salesforce's responsibility, so questions go to the GitHub project.
• Per its README, it talks directly between your browser and Salesforce, and no data is sent to other parties. It uses your logged-in session, which means it needs permission to read cookie information for Salesforce domains.
• It acts as you, so it can only reach data and features your user can already access.
• It uses API calls, so the Salesforce Developers Blog says to be mindful of your limits.
• If you work for a company with rules about browser extensions, ask first.

How to export data with Inspector Reloaded

1. Open Data Export from the extension popup. The how-to lists e as its shortcut key.
2. Type a SOQL query, for example SELECT Id, Name, Phone FROM Account LIMIT 10. To get every field you can access, put the cursor between SELECT and FROM and press Ctrl+Space. New to SOQL? Start with SOQL relationship queries.
3. Run the query. Use the column filter to narrow the results if you need to.
4. Export the result as CSV or Excel. The Data Export documentation has the full list of options.

How to import or update data with Inspector Reloaded

1. Open Data Import from the popup. The how-to lists i as its shortcut key.
2. Pick the object and the action. For an update, the documented steps set the action to Update. If your data has an Id column, the extension can detect the object for you.
3. Paste your data, with a header row naming the fields, for example Id and Phone. It guesses whether you pasted CSV, JSON or Excel data.
4. Map the columns to fields. Use Skip for any column you don't want to load.
5. Click the run button for your action, such as Run Update, and check the results.

The rules from the Data Loader sections still apply. Save a backup export before you update, and try the change in a sandbox first. The documentation also has worked examples, such as mass disabling flows with Data Import.

Data Loader or Inspector Reloaded?

I couldn't find a record limit or a Bulk API option for Inspector Reloaded imports in its documentation, so for million-record loads I use Data Loader. For a quick fix on a few hundred records, I don't. For small one-off imports without any tool, see the Data Import Wizard in this post, and for moving a whole org's data, read Salesforce Data Migration.

Where Data Loader shows up on the Admin exam

The Admin exam's largest section is Data and Analytics Management at 17%, and the exam guide lists importing, updating, transferring, mass deleting, exporting and backing up data, including Data Loader and the Import Wizard. If you're preparing, my free Admin Cert Lab has lessons on exactly this, and my guide to getting Admin certified for free covers practicing in a Developer Edition org.

Frequently asked questions

What is Salesforce Data Loader?

A client application for the bulk import or export of Salesforce data. You use it to insert, update, upsert, delete, hard delete or export records using CSV files, from a wizard or, on Windows, from the command line.

What is Salesforce Inspector Reloaded?

A free, open-source browser extension for Salesforce admins and developers. It adds Data Export and Data Import pages, a record inspector and more, and it's listed for Chrome, Firefox and Edge. It's a community project by Thomas Prouvot and not an official Salesforce product. See the official documentation.

Should I use Data Loader or Salesforce Inspector Reloaded?

For quick exports and small updates, start with Inspector Reloaded because it runs in your browser. Use Data Loader for very large loads with the Bulk API, for scheduled loads from the command line (Windows only), or when you want a tool Salesforce provides itself.

How do I install Data Loader?

Install JRE 17 or later, download Data Loader from the Salesforce developer site, extract the zip and run install.bat on Windows or installer.command on macOS.

Which Salesforce editions can use Data Loader?

Enterprise, Performance, Unlimited and Developer editions. Your user also needs API Enabled and the right object permission for the operation.

Does Data Loader work on a Mac?

Yes. Salesforce lists macOS 13, 14 and 15 as supported. The command line interface is Windows only.

How many records can Data Loader load?

Salesforce says it supports files of up to 5 million records with the Bulk API and 150 million with Bulk API 2.0.

Can Data Loader update existing records?

Yes. An update matches on the record ID. An upsert can match on an external ID field or the record ID, and creates a record when there's no match.

Can I undo a Data Loader load?

There's no undo button. Salesforce's mass update steps say to keep a backup copy of your data and use it to update records back to their previous values. Hard-deleted records can't be recovered from the Recycle Bin.

Hope this helps!

Best,

Nick