Data Migration Tool : Migrating Magento 1 to Magento 2

Data Migration Tool : Migrating Magento 1 to Magento 2

To ease up migration process, Magento released official Data Migration Tool that will help developers migrate data from Magento 1 to Magento 2. The Data Migration Tool is a command-line interface (CLI) that provides verification, progress tracking, logging, and testing functions. It is intended to protect data integrity and reduce downtime during migration.

Let’s have a look at the migration process using Data Migration Tool.


Before you start your migration, you must do all of the following steps:

  • Set up a Magento 2.0 system that at least matches your existing Magento 1 system.
  • Do not start Magento 2 cron jobs.
  • After installation back up or dump your Magento 2 database as soon as possible.
  • Check that the Data Migration tool has a network access to connect the Magento 1 and Magento 2 databases.
  • Replicate your Magento 1.x database and use this data for your migration.
  • Migrate Magento 1 extensions and custom code to Magento 2.
  • Make sure you are using the same released version of both Magento 2 and the Data Migration Tool. To find the version of either package, open composer.json and find the value of “version“.

Install & Upgrade the Data Migration Tool

You can install the Data Migration Tool from either or from a GitHub repository. For the installation process, use the following steps:

  1. Log in to your Magento 2 server as a user with root privileges or switch to the web server user.
  2. Change to Magento 2 root directory.
  3. Use the following commands:
    Enter the commands in the order to Install the tool from

    composer config repositories.magento composer
    composer require magento/data-migration-tool:<version>

    To install the migration tool from GitHub:

    composer config git
    composer require magento/data-migration-tool:<version>
  4. Wait while dependencies are updated/installed.

The versions of the Data Migration Tool and your Magento software must exactly match.

To find the version of the Magento software:

  • If you downloaded the Magento software using a Composer metapackage, use the following command to find the version of Magento:
    php <your Magento install dir>/bin/magento --version
  • If you cloned the Magento 2 GitHub repository, enter the commands:
    cd <your Magento 2 clone directory>
    git branch

To find the version of Data Migration Tool, open composer.json and find the value of “version“.

Before you upgrade the Data Migration Tool, you must upgrade your Magento software and back up the vendor/magento/data-migration-tool directory. The vendor/magento/data-migration-tool directory contains your custom code. It could be modified and can lose your code during the upgrade process.

Use the following steps to upgrade the Data Migration Tool:

  1. Log in to your Magento server as the Magento file system owner.
  2. Change to Magento 2 root directory.
  3. Enter the following command:
    composer require magento/data-migration-tool:<version>

    where <version> is the version of the Magento 2 codebase.

  4. Wait while the above command completes successfully.

We have successfully installed/upgraded the Data Migration Tool.

Configure migration

After you install the data migration tool, the <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ directory contains mapping and configuration files. Before you migrate any data, you must create a config.xml configuration file from the provided sample.

To create a config.xml, use the following steps:

  • Change to <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version> directory.
  • Enter the command: cp config.xml.dist config.xml
  • Add the following details at minimum:
     <database host="" name="magento1" user="root"/>
     <database host="" name="magento2" user="root"/>
     <crypt_key />

    <source>  – configuration for data source (database).
    <destination> – configuration for data destination (database).
    <options> – list of parameters. Contains both mandatory (map_file, settings_map_file, bulk_size) and optional (custom_option, resource_adapter_class_name, prefix_source, prefix_dest, log_file) parameters.
    The <crypt_key> tag can be found in local.xml file which is located in the directory of Magento 1 instance at app/etc/local.xml in <key> tag.

  • When you’re finished, save your changes to config.xml.

The Data Migration Tool uses mapping files to enable you to perform custom database mapping between your Magento 1 and Magento 2 databases. In case Magento 1 contains tables or fields that belong to some extension that does not exist in Magento 2, then these entities can be placed in map.xml to ignore them by Map Step. Otherwise it will show an error message.

For more details on configuration and mapping please refer to Data Migration Tool Internal Specification.

Migrate using the data migration tool

The migration tool operates in three modes to transfer and adapt data from Magento 1 to Magento 2:

  • Settings mode: You should migrate settings first. This mode migrates stores; websites; and all possible configuration settings like shipping, payment, some tax settings etc.
  • Data mode: Migrates database assets in bulk from Magento 1 to Magento 2 database.
  • Delta mode: Incremental migration enables you to migrate only the changes made in Magento 1 since the last time you migrated data.

To run the migration tool to migrate settings, data, or incremental changes, use the following steps.

  1. Log in to your Magento server as the Magento file system owner. If you use the bash shell, you can also use the su <Magento file system owner> -s /bin/bash -c <command> syntax to switch to the Magento file system owner.
  2. Add <your Magento install dir>/bin to your system PATH, to run Magento commands from any directory.
  3. Enter the command:
    bin/magento migrate:<mode> [-r|--reset] {<path to config.xml>}

    <mode> is settings, data, or delta.
    {<path to config.xml>} is the absolute file system path to config.xml; this argument is required.
    [-r|–reset] is an optional argument that starts migration from the beginning. You can use this argument for testing migration.

For example:
To migrate data, use the following command:
bin/magento migrate:data [-r|–reset] {<path to config.xml>}

Logs are written to the <your Magento install dir>/var/ directory. The Data Migration Tool has special handler \Migration\Handler\Timezone for transforming time to a different time zone. Using it you can change time for some fields of database that can be specified in your map.xml file with offset parameter. It also takes care of some behavioural and logical changes in magento 2 from magento 1.

See the official Documentation for more details on Data Migration Tool. Hope this will help you !! 🙂 🙂