Today I will describe how you can perform a Magento 2 upgrade.

When you run an eCommerce store it is vital to stay secure and up to date. You should always look out for the latest M2 version and update promptly.

A word of advice: always backup your files and database before attempting an upgrade. With a platform as complex as Magento 2 you can’t anticipate what is going to happen next. A lot of things might go wrong. You better have a way to go back.

3 Ways to Upgrade Magento 2 Installation

1. Magento composer update. That is using Composer, a terminal command line program.
2. Upgrade Magento from admin using the Web Setup Wizard.
3. Copy the Magento 2 latest version over the old installation.

1. Using Composer

Composer is a dependency manager for PHP. It can help you update your store with minimum hassle.

Instructions to get Composer installed might depend on your server operating system. I will use Debian Linux as an example. Run this SSH command:

It will install Composer systemwide for every user to run. You can always ask your system administrator for assistance.

Now for the upgrade itself you will need to use SSH (Secure Shell). Ask your hosting company for credentials. Login to your server and go to the Magento root folder (usually it is ~/public_html):

Then remove everything in the vendor folder:

Now you can open composer.json file and replace your current version with the latest version sequence (say 2.2.0):

 Set the Latest Magento 2 Version in Composer.json

When that is done go to SSH and update Magento 2 with Composer:

It will ask you for credentials.You may obtain those at Magento marketplace, here is the link https://marketplace.magento.com/customer/accessKeys/:

 Magento Marketplace Public/Private Keys

One thing to remember: username is a public key and password is a private key. That is one of the ways Magento might confuse you.

Once you enter credentials, Composer will go ahead and install the latest Magento 2 version:

 Magento 2 Upgrade with Composer

UPDATE: If you don’t want to edit any files you can run the following command to update to the latest Magento release (2.2.5 at the moment):

If you are running Magento 2 commerce the command will be slightly different:

Replace 2.2.5 with the latest M2 version.

When it is completed, run another SSH command and upgrade the Magento database:

After that you will want to recompile if you are in production mode:

This is it. You’ve successfully performed a Magento 2 upgrade! Now go to the frontend and backend and check everything.

NB: Composer might complain about some PHP extensions not being downloaded. You might want to install them in order to proceed.

2. Using the Web Setup Wizard in the Admin Menu

Magento 2 has a menu option under System > Tools called Web Setup Wizard. You can use it to install extensions bought via the Magento Marketplace. You can also use it to upgrade Magento.

NB: There might not be such a link in your installation. That is a bug which is not fixed as of Magento 2.1.8. Other times the link might disappear after your migrated from Magento 1.

The simple workaround is:

1. Login to Magento backend.
2. Go to http://shop.com/admin_xxx/admin/backendapp/redirect/app/setup/. http://shop.com/admin_xxx is path your backend.
3. You will be automatically redirected to http://shop.com/setup/#/home. There you will select System Upgrade.

 Magento 2 Web Setup Wizard

Click on System Upgrade and follow instructions. They are self-explanatory.

If Show All Versions is checked you can upgrade to unstable development releases.

 Magento 2 web setup wizard upgrade

At Step 2. Readiness Check you might need to upgrade your PHP. Or install plugins. Do as suggested:

 Step 2. Readiness Check

I suggest you backup your files and database manually. Skip Create Backup step. It might hang and you will need to start over.

3. Download the latest version manually and copy/paste

Upgrade this way if the previous two failed for whatever reason.

Download the latest Magento 2 off the official website. Unzip it in your magento main folder. That will overwrite the core files with the new ones.

Then run:

…and

That will upgrade database, compile and deploy static content. It might require some time depending on the number of products, orders and customers you have.

Upgrade is done. Head to frontend and backend and see if everything looks normal.

Should I update my theme after an upgrade?

If it’s a custom-made theme you should definitely contact its developers and ask them to audit it. Tell them you just upgraded M2 and you are not sure if the theme will play well with the current Magento version.

If you purchased a premade theme the vendor usually releases patches for every new M2 version that comes out. Go to templatemonster.com or the site you bought your theme from and see if there are updates available for download.

It is important that you check your Magento frontend pages for any misaligned or missing content. A Magento 2 upgrade can cause serious damage to the look of your website.

What if things go the wrong way?

As with everything in Magento, an upgrade is easier said than done. Below I put together the various errors (and suggested fixes) that might happen during the Magento 2 upgrade process.

1. Component dependency conflict

This problem happens when you try and upgrade Magento via Setup Wizard. At the Readiness Check step it might throw out an exception like this:

 Component Dependency Conflict

There is no real explanation of the issue and you might wonder how to fix it. From my experience dependency conflict in most cases is caused by a third-party extension depending on some old Magento 2 component.

You can resolve the issue by doing the following:

1. Uninstall all custom extensions.
2. Perform an update to the latest Magento version.
3. Reinstall the custom extensions.

In some cases the conflict is caused by a changed composer.json file. Try and restore composer.json to the original version and run Setup Wizard one more time.

2. Can’t create directory

This error happens when you run php bin/magento setup:upgrade right after an upgrade. The complete issue description might look like this:

What should you do in this case? The fix is very simple:

1. Delete var/di folder.
2. Change permissions of var and pub folder to 777 (chmod -R 777 var pub).
3. Run php bin/magento setup:upgrade.
4. Run php bin/magento setup:di:compile.

3. Cannot allocate memory error

If you encounter this error during an upgrade it means there is not enough RAM allocated to PHP processes. Contact your system administrator and ask him/her to increase memory limit to at least 2 Gs.

Of course that means you cannot safely run Magento 2 on a server with less than 2G of available RAM. You should upgrade your plan to meet the minimal hardware requirements.

4. There are no commands defined in the “setup” namespace

This is a generic message that might not be helpful.

There are various ways to try to fix the error:

1. Give full permission to var and pub folders:

2. Inspect your custom modules, make sure every extension’s module.xml has setup_version in it:

3. Inspect your composer.json file. Sometimes an error there might cause a Magento 2 upgrade command to throw the”no commands defined” exception.

5. php bin/magento setup:upgrade not working

From my experience this is mostly related to some custom module having a problem. Try to inspect every one of them to see if you could spot an error.

Try to delete every custom module, update your instance and install them back.

Sometimes clearing generated (the latest 2.2.x versions) or var/di, var/generation (in case of an older Magento 2.1 upgrade) folders helps.