Magento 1 to Magento 2 Migration tutorial: how to migrate your store data


The Magento/Adobe has officially announced the sunset day of Magento 1 support. It will happen in June of 2020. So no more official security updates and patches after that. If you decide to keep your store on Magento 1 and you are on your own to keep it secure. It will also become harder to find a Magento 1 developer and these developers will charge more. That happens with all old software. But now the Magento team can concentrate its resources on developing their next generation e-commerce solution – Magento 2.

So it is good time to migrate your store from Magento 1 to Magento 2. And with help of official Magento Data Migration Tool you can comparatively easily migrate your store data – information about the products you sell, your customers and the orders they placed.

Contact us for expert help with Magento 2 migration! Initial consultation is free.

In this article we will walk you through migrating a stock Magento 1 installation (with sample data) to a fully functional Magento 2 store. This way you will  see what it is like and what kind of problems you may run into. After reading this article if you are not afraid to make you hands dirty with a bit of work typically done by developers, you will be able to migrate a simple store yourself.

But a word or caution:

Every Magento store is a bit different, so your migration process may require some tweaks from one below.

Please, try to do it first with a copy of your store in a safe staging environment.

And don’t forget to backup your code and data. 


Magento 2 is a heavy piece of software that will not run on a slow server. It requires at least 2GB of RAM and 24GB+ SSD. If you don’t have enough RAM, configure a swap file, otherwise it might not install.

We install Magento (with sample data) and Magento 2.2.6 on the same server.

Server’s configuration:

  • Apache 2.4
  • MySQL 5.6
  • PHP-FPM 5.6 for M1 and PHP-FPM 7.1 for M2

We also have to install all required PHP packages, consult the official documentation for a full list. In a real situation these stores can be on separate machines, but the migration process will not be that different.

We install Magento 1 with sample data by following this official tutorial.

To install Magento 2 we follow this official guidelines. The simplest way to install Magento 2 is by using Composer. The command is as simple as

> composer create-project --repository= magento/project-community-edition magento2

Using Composer requires authentication. Use your Magento Marketplace account to generate a pair of 32-character authentication keys to access the repository. Use the Public key as your username and the Private key as your password.

To make the data that we are going to migrate more realistic we add several new products, customers and orders in our M1 store. All of this will be successfully migrated together with the sample data.


The official Migration Guide is a must read if you are considering a migration. Magento 2 migration involves 3 components:

  • data
  • extensions and custom code
  • themes and layout customization

In this article we discuss only data migration. Migrating other components will require help from a developer.

To move data from M1 to M2 we use Data Migration Tool that was created by the Magento Team to help store owners. The whole process splits in three phases or modes: settings mode (migrates the system configuration), data mode (migrates database assets), delta mode (migrates changes since the last run, such as new customers and orders).

Data Migration Tool

To install Data Migration Tool we use Composer. We enter:
> composer config repositories.magento composer
> composer require magento/data-migration-tool:2.2.6
The version of Data Migration Tool must match the version of the Magento 2! In our case we pull Data Migration Tool of version 2.2.6, because we have installed Magento 2.2.6.

To configure Data Migration Tool we have to edit config.xml file, which is in our case located in <Magento 2 install dir>/vendor/magento/data-migration-tool/etc/opensource-to-opensource/ The opensource-to-opensource part must be different if either the source or destination is Magento Commerce. The part must be different if you are migrating another version of Magento 1. In this file we have to specify database credentials and Magento 1 encryption key. The encryption key 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. In our case the edited part of config.xml will look something like this:

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

The migration order is the following: migrate settings, migrate data, migrate changes.

Migrate settings

To run a migration command we always have to specify the path to config.xml file. Lets migrate the settings. We run this command
> bin/magento migrate:settings vendor/magento/data-migration-tool/etc/opensource-to-opensource/

Everything goes well.

Migrate data

The next step is to migrate customers, products, orders and other data. We run the data migration command:
> bin/magento migrate:data vendor/magento/data-migration-tool/etc/opensource-to-opensource/

This time we get many errors. Foreign key constraint errors tell that there is some inconsistency in the database. Probably this has to do with the sample data we installed. To solve this problem we connect to MySQL and delete the orphaned records by running these queries:

DELETE FROM catalog_eav_attribute WHERE attribute_id IN (121, 164);
DELETE FROM catalog_product_entity_int WHERE attribute_id = 121;
DELETE FROM eav_entity_attribute WHERE attribute_id IN (121, 163, 164);

To understand other types of errors we will have to understand how Data Migration Tool works. What it does is it copies data from old tables and columns to new ones. But sometimes new tables and columns will have different names. So the tool will have to map database entities with old names to entities with new names. But it may not know how to map some entities, especially those that have been installed by third-party extensions. When it happens the process stops. We can help it and provide our own mapping rules by editing map-eav.xml and map.xml files.

First we go to opensource-to-opensource directory and copy map-eav.xml.dist to map-eav.xml. Then we go to opensource-to-opensource/ directory and copy map.xml.dist to map.xml. We will add new mapping rules to these new files. To make DMT use these files we have to update config.xml with new file paths.

When we encounter an error that looks like Source documents are not mapped: table1, table2, it means the tool doesn’t know how to map these tables. We choose not to migrate these tables by ignoring them. We should add a new mapping rule for each table:


When we encounter an error that looks like Source fields are not mapped. Document: table. Fields: field1, field2, it means the tool doesn’t know how to map these columns for a given table. We choose not to migrate these columns as well. We should add a new mapping rule for each column:


In our case only one error message has to do with an eav table (can’t map customer_eav_attribute.is_used_for_customer_segment). It means we need to add one rule in map-eav.xml and a lot of rules in map.xml. It will take us about half an hour.

Now we run the previous command with a flag -r (reset):
> bin/magento migrate:data -r vendor/magento/data-migration-tool/etc/opensource-to-opensource/

Everything goes smoothly this time. We needed the flag -r to make the tool run from the start and not from the previous stopping point.

Migrate media files

Media files (images etc.) must be handled differently depending on where they are located. In our case they are located in the file system. We have to copy them manually from <Magento 1 install dir>/media to <Magento 2 install dir>/pub/media.
> cp -r <Magento 1 install dir>/media/* <Magento 2 install dir>/pub/media
They also can be located in the database. In this case just synchronize your media storage database from the web admin before performing data migration. Media files will be migrated together with the data.

Migrate changes

After you have migrated your data, new customers may register in your old store, new orders can be created and so on. To migrate this new data you will need what is called delta migration. Delta migration enables you to migrate only the changes made in Magento 1 since the last time you migrated data. These changes are: data that customers added via storefront (created orders, reviews, changes in customer profiles, etc.), all operations with orders in the Magento Admin panel.

For the sake of an experiment, we add a couple of new customers and a couple of new orders in our M1 store. We perform a delta migration with this command:
> bin/magento migrate:delta vendor/magento/data-migration-tool/etc/opensource-to-opensource/

This command runs in an infinite loop picking up new changes at each iteration. We have to stop it by pressing Ctrl + C. We go to M2 web admin and check that all new customers and orders have been migrated successfully. Keep in mind, that delta migration will not pick up new products, it means that you should not add new products after beginning a migration.

Final steps

The process of migration has been finished. We flush all Magento 2 cache types and reindex all Magento 2 indexers:
> bin/magento cache:flush
> bin/magento indexer:reindex
We pull the plug on our old store and make the new store go live. The new store’s design sometimes looks broken due to differences in themes. But overall it looks pretty decent.

What can’t be migrated

You will not be able to migrate your website look and feel (theme). Magento 2 has a whole different front-end system. A better choice would be to buy a stock M2 theme or to hire an expert to create a custom one. There is no tool to port your extensions and custom code too. Extension vendor may have M2 version of the extension you use, but many M1 extensions still don’t have M2 version. You will have to find an alternative or to refactor the extension manually. Be ready to hire a skilled a Magento 2 developer for this job.

Get fresh eCommerce insights weekly

Subscribe to our mailing list

* indicates required

No, I don't need insights. Just close this pop-up

Consider changing your eCommerce platform?

Learn how to avoid nine deadly mistakes that can ruin your business.

Get free whitepaper from Magenable

Get whitepaper

Get free whitepaper!