Salesforce Data Loader: A Step-by-Step Guide for Admins

Illustration of a CSV file flowing through Data Loader into Salesforce, with insert, update, upsert and delete operations labeled

Salesforce Data Loader is Salesforce's desktop application for loading and exporting records in bulk. Salesforce's Data Loader Guide describes it as "a client application for the bulk import or export of data" that you use "to insert, update, delete, or export Salesforce records." It runs on macOS or Windows and reads and writes CSV files.

This guide walks admins through each operation step by step: insert, update, upsert, delete and export. It also covers the settings that cause the most damage when left at their defaults, and ends with a safety checklist to run before any large load.

When to use Salesforce Data Loader instead of the Data Import Wizard

Salesforce gives admins two built-in tools for loading data, and its When to Use Data Loader page sets out the split.

Use the Data Import Wizard when you're loading less than 50,000 records, the object is supported by the import wizards, your target object has fewer than 50 fields, and your data doesn't include complex field mappings. You open it from Setup by entering Data Import Wizard in the Quick Find box.

Use Data Loader when the object isn't supported by the wizard, your data includes complex field mappings that you must load consistently on a regular basis, you want to schedule regular data loads such as nightly imports, or you want to export your data for backup purposes. The same page says Data Loader supports CSV files with a maximum of 150,000,000 records, and that for more than 150 million records Salesforce recommends working with a Salesforce partner.

Data Loader is available in Enterprise, Performance, Unlimited and Developer editions. Salesforce also documents a web-based tool, Dataloader from MuleSoft, which is a separate product. This guide covers the desktop application.

Before you start: install, permissions and login

The installation guide lists what you need:

  • Java. Install Java Runtime Environment (JRE) version 17 or later before installing Data Loader. Salesforce no longer bundles Java with the Windows installer, so this step is not optional.
  • The installer. Download Data Loader from the Salesforce Developers tools page, extract the zip file, then run install.bat on Windows or the installer command file on macOS. On recent macOS versions you may need to allow the app in Privacy and Security settings the first time it opens.
  • Permissions. The user who logs in needs API Enabled, the user permission for the operation you're running, and Bulk API Hard Delete only if you configure Data Loader to use Bulk API to hard-delete records.
  • Login. Data Loader supports OAuth 2.0 Web Server Flow (Data Loader version v64.0.1 and later) or password authentication. If your org restricts login IP addresses and you log in from outside them, add your security token to the end of your password. The production and test authentication endpoints default to login.salesforce.com and test.salesforce.com, and Salesforce recommends changing these to the My Domain URLs of your orgs.

Salesforce also documents how to connect Data Loader through an external client app with PKCE, for Data Loader version 64.0.2 or later. If your security team controls which apps can connect to Salesforce, that page is the one to share with them.

The settings to check before every load

Open Settings, then Settings again, before you run anything. The configuration page lists every option. These are the ones that matter most:

  • Import batch size. The number of records sent in each call. The maximum is 200 with the default SOAP API and 10,000 when Use Bulk API is selected. With Bulk API 2.0, Data Loader handles batch size automatically.
  • Use Bulk API and Use Bulk API 2.0. Bulk options suit large loads. Some settings below are not available when a Bulk option is on.
  • Insert null values. When selected, blank values in mapped columns are written as nulls, which overwrites existing data. Leave it off unless you mean to clear fields.
  • Allow field truncation. Selected by default. It cuts values that are too long for the field instead of failing the row, so you may not notice data was shortened.
  • Time Zone. Defaults to your computer's time zone. If your file's dates and times come from another system, set this to match or every value shifts.
  • Read all CSVs with UTF-8 encoding and Write all CSVs with UTF-8 encoding. Turn these on if your data has accented characters or non-Latin scripts.
  • Use European date format. Turn this on if your file uses day before month.
  • Start at row. If a load stops partway, this lets you resume from a given row instead of reloading records that already succeeded.

How to insert, update, upsert or delete records step by step

Salesforce's insert, update and delete guide uses the same wizard for every operation. Here is the flow:

  1. Prepare the CSV. The first row holds column headers. For updates and deletes, include the Salesforce record Id column. For upserts, include the Id or an external ID column.
  2. Choose the operation. Click Insert, Update, Upsert, Delete or Hard Delete, then log in.
  3. Choose the object. Select the object from the list. Select Show all objects if the one you need is not listed. Click Browse and select your CSV file.
  4. Map the fields. Click Choose an Existing Map if you saved one for this file layout, or Create or Edit a Map to match each CSV column to a Salesforce field. Save the map if you will run the same load again.
  5. Pick the output folder for the success and error files, then click Finish.
  6. Read the results. Data Loader writes two files: one whose name starts with "success" and one whose name starts with "error". Click View Successes and View Errors. The error file gives the reason each row failed, so you can fix those rows and load only them.

Insert

Insert creates new records and returns their new Ids in the success file. Keep that file: it is the easiest way to update or remove the same records later.

Update

Update changes existing records matched by Id. Only the columns you map are loaded, and blank cells do not clear existing values unless Insert null values is on, which is why that setting is worth checking every time.

Upsert

Upsert updates records that match and creates the rest. The guide says the matching column "is either an external ID (a custom field with the External ID attribute) or ID (the Salesforce record ID)." If the object has no external ID fields, Data Loader matches on Id. During an upsert you choose the field to match on, and you can also match related records, such as the parent account, by an external ID.

Delete and Hard Delete

Delete sends records to the Recycle Bin. Salesforce Help says deleted items remain in the Recycle Bin for 15 days, during which users can restore them. Hard Delete skips that safety net: the guide says hard-deleted records "are not stored in the Recycle Bin and are eligible for deletion." It also warns that "Data Loader deletes records based on the IDs in the CSV file, not the object selected", so a file built from the wrong report deletes the wrong records even if you picked the right object.

A worked example: upserting contacts from another system

Say your marketing platform exports contacts every week, and you want Salesforce to update the ones it already has and create the rest without duplicates.

  1. Ask for a custom field on Contact, for example Marketing_ID__c, with the External ID attribute. Have the marketing platform's own record ID in every row of the export.
  2. In the CSV, keep a column for Marketing_ID__c plus the fields you want to load, such as FirstName, LastName, Email and the parent account's external ID if you match accounts that way.
  3. Log in to a sandbox first. Set the Time Zone and UTF-8 options to match the file, and leave Insert null values off.
  4. Choose Upsert, select Contact, then choose Marketing_ID__c as the field to match on. If you link contacts to accounts by an external ID, set that match for the Account lookup.
  5. Map the columns, save the map, run the load, and open the success and error files. Check a few contacts in the sandbox to confirm that existing ones were updated rather than duplicated.
  6. Run the same saved map against production, starting with a small file, then the full export.

A header row for that file might look like this:

Marketing_ID__c,FirstName,LastName,Email
MKT-00412,Dana,Lopez,dana.lopez@example.com
MKT-00413,Sam,Okafor,sam.okafor@example.com

How to export data with Data Loader

Exports are the safest Data Loader operation and the one to run before every change. The export guide says to click Export, or Export All if you also want archived activity records and soft-deleted records. You choose the object, pick the fields and optional conditions, and Data Loader writes a CSV. Two cautions from the same page: choosing an existing CSV file overwrites it, and attachments cannot be exported with Data Loader, so use the weekly export for those.

Salesforce Data Loader safety checklist

Run this checklist before any load that changes or removes data:

  • Export the records you are about to change, with Id and every field you will touch, and keep the file somewhere safe.
  • Confirm the org has a recent full backup. Trailhead's Export Data unit describes the Data Export service, which you can run once every 7 days or 29 days depending on your edition.
  • Test the load in a sandbox, including what your validation rules, flows and triggers do with it.
  • Check Insert null values, Allow field truncation, Time Zone and the UTF-8 options.
  • Load a small sample first and open the success and error files before the full run.
  • For deletes, check that every Id in the file belongs to the object you mean, and prefer Delete over Hard Delete so the Recycle Bin can catch mistakes.
  • Keep the success file from every insert. It holds the new Ids you need to undo the load.
  • Write down what you loaded, when and why. Our daily, weekly and monthly Salesforce admin task checklist shows where data loads fit in a regular routine.

Data Loader from the command line

Admins who run the same load every night can use the command-line interface. The installation guide says the Data Loader command-line interface is supported for Windows only, so plan a Windows machine or server for scheduled runs. It also notes that if a login fails after an upgrade, you may need to encrypt your password again.

Data Loader is for records, not configuration

Data Loader moves records. It does not move fields, layouts, flows or permission sets. When a release needs both new fields and data in them, deploy the configuration first, for example with a Salesforce change set built and deployed step by step, then load the data.

Data loads are routine work that still needs care, which is why Cirra AI is building Cirra Admin to help admins with requests like these while the admin keeps control of what changes. Today, Cirra AI's Salesforce Admin MCP Server can query, insert, update and delete records, including bulk loads, from the AI client you already use, working as the connected user within that user's permissions. You can read more about how Cirra AI supports Salesforce admins. Whatever tools you use, check the Data Loader Guide for your version, because settings and login options change between releases.

Frequently asked questions

What is Salesforce Data Loader used for?

Salesforce Data Loader is a client application for the bulk import or export of data. Admins use it to insert, update, upsert, delete, hard delete and export Salesforce records from CSV files, usually for loads too large or complex for the Data Import Wizard.

How many records can Salesforce Data Loader handle?

Salesforce says Data Loader supports CSV files with a maximum of 150,000,000 records. For more than 150 million records, Salesforce recommends working with a Salesforce partner.

What is the difference between Data Loader and the Data Import Wizard?

Salesforce recommends the Data Import Wizard for fewer than 50,000 records on supported objects with fewer than 50 fields and simple mappings. Data Loader suits larger loads, unsupported objects, complex mappings that repeat, scheduled loads and data exports.

Do I need Java to run Salesforce Data Loader?

Yes. Install Java Runtime Environment version 17 or later before you install Data Loader. Salesforce no longer bundles Java with the Windows installer.

Can I undo a Data Loader delete?

A normal delete sends records to the Recycle Bin, where they stay for 15 days and can be restored. A hard delete skips the Recycle Bin, so those records cannot be restored from it. Export the records before you delete them.

Does Salesforce Data Loader work on a Mac?

Yes. Data Loader is available for macOS and Windows. The command-line interface is supported on Windows only.

Share the Post:

Related Posts