Get Started.

Table of Contents



Overview ⇧

The SFDX Data Move Utility (SFDMU) is a powerful and versatile tool designed to facilitate complex data migration and synchronization processes between Salesforce organizations. As a fully-featured, open-source solution, SFDMU offers significant advantages for Salesforce administrators and developers looking to streamline their data handling practices.

👉 Use the SFDMU GUI Application to easily configure and run the migration jobs.
With this Desktop Application, there’s no need for Notepad and Console. All tasks are performed visually, significantly simplifying migration job management.

SFDMU New Improved Version of the Plugin ⇧

The new improved version of the plugin described in this section is built on the new SF CLI API and includes the latest available security updates. The latest pre-refactoring line was v4.39.0 from the previous engine generation. We recommend moving to the new improved version of the plugin if it works correctly in your environment. If it does not work correctly yet, temporarily roll back to v4.39.0.

What Changed in the New Improved Version of the Plugin ⇧

The list below is based on the official old-vs-new engine comparison and includes all new/changed/legacy differences between the old and new engines.

Breaking Changes and Migration Notes for the New Improved Version of the Plugin ⇧

The following items can break existing automation or change behavior of existing jobs:

  • standalone Node.js/module execution mode is no longer supported; use sf sfdmu run.
  • default apiVersion is now auto-resolved from org capabilities, so behavior can differ from fixed-version legacy automation.
  • --filelog now defaults to 0, so .log files are not guaranteed unless you enable logging (--diagnostic is recommended).
  • --verbose, --concise, and --usesf no longer change runtime behavior.
  • operation validation is stricter; invalid or not-allowed operations are rejected earlier.
  • CSV delimiter precedence changed:
  • CSV id/reference handling became stricter (excludeIdsFromCSVFiles + new post-processing flow).

How to Adjust Existing Jobs and Source CSV Files ⇧

  1. API version:
    • if your automation depends on a fixed version, pin apiVersion explicitly.
  2. File logging:
    • --filelog now defaults to 0; use --filelog 1 or --diagnostic when logs are required.
    • if logs must be shared outside your team, use --anonymise to hash sensitive values in .log files.
  3. Legacy CLI flags:
  4. Operation validation:
    • verify each object operation against target CRUD permissions; invalid operations are now rejected earlier.
  5. CSV delimiter precedence:
  6. CSV id/reference behavior:
    • if you migrate using old CSV files, re-export them once with the new version before production runs;
    • the engine always adds relationship reference columns with __r;
    • when excludeIdsFromCSVFiles=true, the engine removes raw Id and lookup ...Id columns;
    • __r means relation-by-reference (not Salesforce record Id), mapped by parent external-id values;
    • examples of __r columns:
      • Account__r.Name
      • Account__r.External_Id__c
      • Parent__r.Name

Temporary Rollback to Previous Stable Plugin ⇧

If the new improved version of the plugin does not work for your scenario yet, you can temporarily install the previous line (4.39.0):

# Remove current plugin
sf plugins uninstall sfdmu

# Install previous stable version
sf plugins install sfdmu@4.39.0

To switch back to the latest line later:

sf plugins install sfdmu@latest

Reporting Bugs in the New Improved Version of the Plugin ⇧

If you find a bug in the new improved version of the plugin, please report it. For issue analysis, run with --diagnostic and --anonymise, then attach the full generated log file; without the complete diagnostic log, troubleshooting is usually not possible.

For the full masked/non-masked list, see: /full-documentation/reports/the-execution-log#what-is-masked-and-what-is-not

Example:

sf sfdmu run --sourceusername source@name.com --targetusername target@name.com --diagnostic --anonymise

Please include:

  • full .log file generated by the run;
  • your export.json and related CSV samples (sanitize secrets or sensitive data if needed);
  • exact command line and plugin version.

Step 1. Install the SFDMU ⇧

Before you install and use the SFDMU Plugin, ensure that the SF CLI is installed on your system.

Use the following commands to manage SFDMU installation:

# Uninstall an old version of the Plugin, if any:
$ sf plugins uninstall sfdmu

# Install the latest version of the Plugin:
$ sf plugins install sfdmu

# Or install the latest version using an explicit latest tag:
$ sf plugins install sfdmu@latest

# Or install a specific plugin version:
$ sf plugins install sfdmu@<version>
Notes:
  • If you encounter permission issues on MacOS, use the sudo prefix with the installation command:
$ sudo sf plugins install sfdmu

Step 2. Configure the Migration Job ⇧

Basic Configuration Example: Upserting Accounts ⇧

Create an export.json file like this for basic account upserts:

{
    "objects": [
        {
            "query": "SELECT Id, Name FROM Account",
            "operation": "Upsert",
            "externalId": "Name"
        }
    ]
}

Advanced Configuration Example: Upserting Multiple Related SObjects ⇧

Assume, the data model appears as the following:

image

For this data model with complex circular relationships, use a configuration like this to maintain relationships during upserts:

{
    "objects": [
        {
            "query": "SELECT Id, Phone, TestObject3__c FROM Account WHERE Name LIKE 'TEST_ACC_%'",
            "operation": "Upsert",
            "externalId": "Name"
        },
        {
            "query": "SELECT Id, Account__c, TestObject3__c, RecordTypeId FROM TestObject__c",
            "operation": "Upsert",
            "externalId": "Name"
        },
        {
            "query": "SELECT Id, Account__c, TestObject__c FROM TestObject2__c",
            "operation": "Upsert",
            "externalId": "Name"
        },
        {
            "query": "SELECT Id, TestObject2__c FROM TestObject3__c",
            "operation": "Upsert",
            "externalId": "Name"
        }
    ]
}

Important Notes ⇧

  • Ensure the correct spelling of object API names in export.json queries as they are case-sensitive.

Step 3. Run the Migration Job ⇧

Navigate to your export.json directory and execute the appropriate command to initiate migration:

  • Direct migration between Salesforce orgs:
$ sf sfdmu run --sourceusername source@name.com --targetusername target@name.com
  • Import data from CSV files:
$ sf sfdmu run --sourceusername csvfile --targetusername target@name.com
  • Export data into CSV files:
$ sf sfdmu run --sourceusername source@name.com --targetusername csvfile

Demonstration Video ⇧

Watch SFDMU in action in this demonstration video.

This demonstration provides all the essential steps and configurations to get started with SFDMU for efficient data migration in Salesforce:

Related Articles ⇧

Last updated on 20th Feb 2026