Chapter 6: Magento 2 – Migrating from Magento 1.9.x

The Guide:

This Chapter:


Magento 2 was much anticipated and contained a myriad of improvements that users have been longing for.

Magento 1 is no longer supported as of June 2020 (this is known as its “End of life”) and means patches will no longer be available, and you may be more susceptible to hacks or data leaks.

Almost everything can be migrated from Magento 1.9 to 2 too, including products, product categories, manufactures, taxes, customers, orders, coupons, multi-store, CMS pages.

Store owners must migrate to Magento 2 as soon as possible and start making the most of some of the key features of Magento 2.x:

  • Enhanced checkout,
  • A more user-friendly admin panel,
  • Better search and SEO features,
  • Improved product section,
  • User-friendly approach,
  • More efficiency and performance (including site speed),
  • Increased integrations,
  • Mobile-optimised experiences.
  • Advanced reporting.

Making this change needs to be handled correctly, and that includes creating a migration plan. Be mindful of the time, though. Migration can be a time-consuming process; this is normal. A typical migration can take anywhere from a few weeks to several months.

Note: Click on the icons to get extended information and the rationale behind each change or click here to show them all.

Before You Start

Before you begin your upgrade from Magento 1.9.x to Magento 2.x, it is crucial that you:

  • Make a full back-up of your Magento store files, databases, and folders.
  • Analyse what extensions etc. has / can be removed or maintained in your new Magento 2.x store.
  • Ensure your current custom code, extensions, and themes are still compatible.

Prep With Google Analytics

PushON finds that this is an excellent way to ensure that your URLs that provide most of your traffic are migrated appropriately.

To do this, log in to Google Analytics and navigate to Behaviour > Site Content > Landing Pages, and change the date in the top right corner to the last 6 months.

GA set up

Make a note of your URLs that are providing most of your traffic. You can choose to filter by Organic users if you wish too.

Prep With Google Search Console

We also recommend looking at your Google Search Console data and once in your account click to Performance > then change the date to the last 6 months.

You will then be able to see your top keywords, their impressions, and clicks. You can then work to ensure these queries continue to perform well once your site has been migrated.

GSC set up






Dry Run

Before you start your migration on the production environment, why not first conduct all of the necessary migration steps on your testing environment first to ensure everything works as it should. This is an often overlooked step, but one that can save you time in the future. It also allows you to test your new site, meticulously.

  1. Copy your Magento 1.x store to a staging server.
  2. Fully migrate the replicated Magento 1 store to Magento 2.x
  3. Thoroughly test the new store.
    1. You must ensure that all payment methods work, orders can be placed correctly, and everything has been migrated as it should.
    2. You can also use this time to train your team on the new features of Magento 2, so they can hit the ground running when your new website fully launches.

Migration Plan

Magento migration comes in four stages.

  1. Theme Migration,
  2. Extension Migration,
  3. Customisations,
  4. Data Migration.

You should have a plan in mind for when you would like your new Magento 2 store to go live. For example, festive periods or during peak/sale periods probably would not be the best time. It is best to launch during slower seasons to avoid losing revenue or large amounts of traffic.

There is also the chance of some downtime during the launch. But if the migration is done correctly, then this should not last any longer than 30 minutes. We would suggest planning this accordingly as much as possible and try to launch during quieter hours – this could be earlier in the morning or later in the day depending on the nature of the business. Do not launch on the weekend or a Friday though. We know this may sound like a good idea, but you need your developers to be available if something goes wrong, and if you launch on the weekend, they may not be around to help you.

It is good practice to let your customers know that they can expect some downtime too. Prepare a maintenance page and offer them a way to get in touch if they have issues.

It is also good to agree on a cut-off time with your existing store where everyone agrees to stop developing or adding new features or modules. This is because as you move to Magento 2, they will likely have to be built from scratch anyway to work with the new platform.

You also need to remember that while you work on the new site, the existing website will still be taking new orders. It is imperative not to lose the most recent orders upon launch, so make sure that you migrate your order database too.

You may have to manually copy your media files from the magento1-root/media directory to magento2-root/pub/media.

Theme Migration

First things first, it is not possible to directly migrate your Magento 1 theme into Magento 2. Developers will need to check if the same theme is available (which will simplify the migration progress) or look at ways to modify existing themes to make them compatible with Magento 2 standards.

Otherwise, you will have to choose a new theme from the Magento Marketplace. Alternatively, developers can create custom Magento 2 themes that work for your website.

Extension Migration

Extensions are used to provide extra or new features that extend the capabilities of your Magento store. They can cover anything from accounting and finance, customer support, marketing, sales, and site optimisation.

In the same way as before, it is essential to make sure that the extensions you used on Magento 1 are still available in Magento 2.x. It is not possible to migrate the same versions from Magento 1 into Magento 2, as you will come across compatibility issues.

If they are, then the same extensions can be migrated and integrated without issue. Otherwise, your developers may have to convert the code for you, or you can find the extensions you need from the Marketplace.

We would recommend only installing the extensions that are required for your store to function; installing too many unnecessary ones can affect site speed.


Mostly, the custom code you use should be compatible with Magento 2.

Using the Code Migration Tool to migrate your customisations into Magento 2 will save you much time and work with this process. After following the procedure, you will need to manually edit some of the generated files due to the structural differences between the platforms.

Data Migration

To migrate your data into Magento 2, you can install the Data Migration Tool. The tool should be configured to the same version of Magento 2.x.This means that if you are using Magento 2.2.0, then the Data Migration Tool 2.2.0 should be installed.

To find the version of your store, navigate to the root directory of your Magento 2 via SSH and enter this command:

php bin/magento --version

You must update the location of the Data Migration Tool in the composer.json file to work. To do that, run the following commands:

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

In the above command, <version> refers to the version of the Data Migration Tool that must match the Magento 2 version discovered earlier. For example, if you are using Magento version 2.2.0, the command should read:

1. composer config repositories.magento composer
2. composer require magento/data-migration-tool:2.2.0

Configure The Tool

Once installed, we need to set the configuration for the migration to take place. From inside the data-migration-tool/etc folder, you need to locate three folders with the names ce-to-ce, ce-to-ee, ee-to-ee.

The folder ce-to-ce has scripts and configuration files for migrating data from Magento 1.x CE to Magento 2.x CE (Community Edition), and the other folders contain the respective files including EE (Commerce Edition).

Navigate to the folder you need for the migration. This means, if you are migrating from the community edition to the Commerce edition, you need to choose ce-to-ee. From there, create a config.xml file.

If you are migrating from Magento 1.x Open Source to Magento 2.x Commerce Edition, then navigate to:

<Magento 2 root dir>/vendor/magento/data-migration-tool/etc/opensource-to-opensource/<Magento 1.x version> 

Then rename the config.xml.dist to config.xml. This file should then be opened in a file editor of your choice and specify:

1. <source>
3. <database host="localhost" name="Magento1-DB-name" user="DB-username" password="DB-password"/>
5. </source>
7. <destination>
9. <database host="localhost" name="Magento2-DB-name" user="DB-username" password="DB-password"/>
11. </destination>
13. <options>
15. <crypt_key>Magento1-Encrypted-Key</crypt_key>
17. </options>

In this example, <source> has the database information of Magento 1 and <destination> has the relevant database information of Magento 2.

<crypt_key> is mandatory and needs to be filled before running. This is the encryption key of your Magento 1 store and can be found in the prior run. It is the encryption key of the Magento 1 store and can be found in:

<Magento 1 root dir>/app/etc/local.xml file, with the <key> tag.

When finished, save the config.xml file.

Migrate Settings

Next, we can use the Data Migration Tool to migrate settings into Magento 2. These settings include stores, websites, system configurations such as shipping, payment, tax settings, etc.

Navigate to your Magento 2 root directory via SSH terminal and run the following command:

1. php bin/magento migrate:settings --reset <path to your config.xml>

Once the settings migration is complete, a successful message will be displayed.

Migrate Data

Next, we need to migrate the database assets, which includes products, categories, customer information, orders, configurations, etc.). To do so, enter the following:

1. php bin/magento migrate:data --reset <path to your config.xml>

As this runs, the tool will save its current progress, and in the case of an error, it will stop the process and resume from the last known good state. The tool may also report some errors during the migration, in which case you should refer to the troubleshooting page of the Magento 2 Data Migration Tool for more assistance.

Once the data migration is complete, a successful message will be displayed.

Go Live

Once the new store is up to date with Magento 1 and functioning as it should, we would suggest:

  1. Put your Magento 1 store into Maintenance Mode – which will start your downtime.
  2. Enter Control+C in the Migration Tool command window to stop any incremental updates.
  3. Start your Magento 2 cron jobs.
  4. Inside Magento 2, re-index the stock indexer.
  5. Cache pages in your Magento 2 store in advance of customers using your storefront.
  6. Perform any necessary final verification for Magento 2.
  7. Change DNS, load balancers, etc. to point to the new production partner – which will end your downtime.
  8. Your new store should now be ready to use, and your customers can use your store as usual and perform normal activities.

Keep reading to discover more about Best Practices and Advanced Setup for Magento 2 in the next chapter.