Configure migration

Overview of Data Migration Tool configuration

After you install the data migration tool, the following directory contains mapping and configuration files:

  • Magento CE:

    • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ce-to-ce: Configuration and scripts for migrating from Magento 1 CE to Magento 2 CE
  • Magento EE:

    • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ce-to-ee: Configuration and scripts for migrating from Magento 1 CE to Magento 2 EE
    • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ee-to-ee: Configuration and scripts for migrating from Magento 1 EE to Magento 2 EE

The preceding directories contain subdirectories for each supported version.

Configuring the migration

Before you migrate any data, you must create a config.xml configuration file from the provided sample.

To create a configuration file:

  1. Log in to your Magento server as, or switch to, the Magento file system owner.

  2. Change to the following directory:

    <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version>
  3. Enter the following command to create a config.xml from the provided sample:

    cp config.xml.dist config.xml
  4. Open config.xml in a text editor.

  5. Specify the following at minimum:

    <database host="" name="magento1" user="root"/>
    <database host="" name="magento2" user="root"/>
    <crypt_key />

The <crypt_key> tag is mandatory to fill. It 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

Optional parameters:

  • Database user password: password=<password>

  • Table prefix: <source_prefix>, <dest_prefix>

For example, if your database owner’s user name is root with password pass and you use the prefix magento1 in your Magento 1 database, use the following in config.xml:

    <database host="" name="magento1" user="root" password="pass"/>
    <database host="" name="magento2" user="root" password="pass"/>

When finished, save your changes to config.xml and exit the text editor.

Work with configuration and mapping files

The Data Migration Tool uses mapping files to enable you to perform custom database mapping between your Magento 1 and Magento 2 databases, including:

  • Changing table names

  • Changing field names

  • Ignoring tables or fields

  • Adapt transferring data of a field to Magento 2 format

Mapping files for supported Magento versions are located in subdirectories of <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc

To use the mapping files:

  1. Rename or copy them to remove the .dist extension.

  2. Edit them using the schema located in

    <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc.

  3. Then change config.xml in <options> node with the new name of the file.

The <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc and <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<ce version> directories contain the following configuration files:

Even though you will be working with map.xml.dist file most of the time, the following table discusses each mapping and other files.

Mapping file name Description
class-map.xml.dist Dictionary of class mappings between Magento 1 and Magento 2
config.xml.dist Main configuration file that specifies the Magento 1 and Magento 2 database configurations, step configuration, and links to mapping files
EE only. customer-attr-document-groups.xml.dist List of tables used in the custom customer attributes step.
EE only. customer-attr-map.xml.dist Map file that is used in Custom Customer Attributes Step.
deltalog.xml.dist Contains the list of tables required for database routines setup.
eav-attribute-groups.xml.dist Contains list of attributes that are used in Eav Step.
eav-document-groups.xml.dist Contains list of tables that are used in Eav Step.
log-document-groups.xml.dist Contains list of tables that are used in Log Step.
map-eav.xml.dist Map file that is used in EAV Step.
map-log.xml.dist Log mapping file.
EE only. map-sales.xml.dist Map file that is used in SalesOrder step.
map.xml.dist Mapping file required for the map step.
settings.xml.dist Setting migration configuration file that specifies rules required for migrating the core_config_data table.
customer-attribute-groups.xml Contains list of attributes that are used in Customer Attributes Step.
customer-document-groups.xml Contains list of tables that are used in Customer Attributes Step.
map-customer.xml Map file that is used in Customer Attributes Step.
order-grids-document-groups.xml Contains list of tables that are used in OrderGrids Step.

You can refer to Data Migration Tool Technical Specification for more details.

Next step

Migrate using data migration tool