Magento 2.1.18 is the final 2.1.x release. After June 2019, Magento 2.1.x will no longer receive security patches, quality fixes, or documentation updates.
To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

Technical Bulletin

These instructions apply to anyone upgrading to Magento Open Source or Magento Commerce version 2.1 (including a Release Candidate).

See one of the following sections for more information:

Upgrade to Magento Open Source or Commerce version 2.1 without sample data

Upgrades to version 2.1 without sample data can fail because of an issue with the Magento composer-installer component. It doesn’t correctly detect code changes and therefore doesn’t update the cache and compiled code directories properly. As a result, fatal errors display during the upgrade.

To address the issue, you must apply a patch.

Get the patch

Use the following instructions to get the patch named MDVA-532.*, then transfer it to your Magento server.

To get the patch:
Magento edition Patch location
Magento Open Source

www.magento.com/download

Follow the instructions on your screen to download the desired patch.

Magento Commerce merchant portal Use the following steps:
  1. Go to www.magento.com
  2. In the top horizontal navigation bar, click My Account.
  3. Log in with your Magento username and password.
  4. In the left navigation bar, click Downloads.
  5. Click Magento Enterprise Edition 2.X > Magento Enterprise Edition 2.x Release > Support Patches
  6. Follow the instructions on your screen to download the desired patch.
  7. </ul> </li>
  8. Transfer the patch to your development system.
Magento EE partner portal Use the following steps:
  1. Log in to partners.magento.com
  2. Click Magento Enterprise Edition > Magento Enterprise Edition 2.X > Magento Enterprise Edition 2.x Release > Support Patches.
  3. In the left navigation bar, click Downloads.
  4. Follow the instructions on your screen to download the desired patch.
  5. Transfer the patch to your development system.

Apply the patch

As the Magento file system owner, extract the patch in your Magento installation directory.

To apply the patch:

To apply a patch:

  1. Copy the patch file to your Magento installation directory.
  2. As the Magento file system owner, use one of the following commands to extract it:
Patch file format Command to extract
.zip unzip -o <patch name>.zip
.tar.gz tar -zxf <patch name>.tar.gz
.tar.bz2 tar -jxf <patch name>.tar.bz2

If you don’t have command line access to your Magento server, extract the patch locally and transfer the files to the server using an FTP application.

For example, to change to the magento_user and extract MDVA-532.zip into /var/www/magento2, enter:

1
su magento_user && cd /var/www/magento2 && unzip -o MDVA-532.zip

Complete your upgrade

After applying the patch, complete your upgrade as follows:

Command-line upgrade to Magento Open Source or Commerce version 2.1 with sample data

Command-line upgrade to Magento 2.1 with sample data

These instructions apply to Magento Open Source and Magento Commerce users only if all of the following are true:

  • You have installed optional sample data
  • You are upgrading to Magento 2.1 (including a Release Candidate) from any earlier version using the command line

To upgrade to Magento 2.1 sample data using the command line:

  1. Log in to your Magento server as, or switch to, the Magento file system owner.
  2. Change to the Magento installation directory.
  3. Back up your current composer.json file:
    1
    
    cp composer.json composer.json.bak
    
  4. Upgrade the Magento software version using commands of the following format:
    1
    
    composer require <product> <version> --no-update
    
    1
    
    composer require <sample data module-1>:<version> ... <sample data module-n>:<version> --no-update
    
    • Example for Magento Open Source:
      1
      
       composer require magento/product-community-edition 2.1.0 --no-update
      
      1
      
       composer require magento/module-bundle-sample-data:100.1.0 magento/module-widget-sample-data:100.1.0 magento/module-theme-sample-data:100.1.0 magento/module-catalog-sample-data:100.1.0 magento/module-customer-sample-data:100.1.0 magento/module-cms-sample-data:100.1.0  magento/module-catalog-rule-sample-data:100.1.0 magento/module-sales-rule-sample-data:100.1.0 magento/module-review-sample-data:100.1.0 magento/module-tax-sample-data:100.1.0 magento/module-sales-sample-data:100.1.0 magento/module-grouped-product-sample-data:100.1.0 magento/module-downloadable-sample-data:100.1.0 magento/module-msrp-sample-data:100.1.0 magento/module-configurable-sample-data:100.1.0 magento/module-product-links-sample-data:100.1.0 magento/module-wishlist-sample-data:100.1.0 magento/module-swatches-sample-data:100.1.0 magento/sample-data-media:100.1.0 magento/module-offline-shipping-sample-data:100.1.0 --no-update 
      
    • Example for Magento Commerce:
      1
      
      composer require magento/product-enterprise-edition 2.1.0 --no-update
      
      1
      
      composer require magento/module-bundle-sample-data:100.1.0 magento/module-widget-sample-data:100.1.0 magento/module-theme-sample-data:100.1.0 magento/module-catalog-sample-data:100.1.0 magento/module-customer-sample-data:100.1.0 magento/module-cms-sample-data:100.1.0  magento/module-catalog-rule-sample-data:100.1.0 magento/module-sales-rule-sample-data:100.1.0 magento/module-review-sample-data:100.1.0 magento/module-tax-sample-data:100.1.0 magento/module-sales-sample-data:100.1.0 magento/module-grouped-product-sample-data:100.1.0 magento/module-downloadable-sample-data:100.1.0 magento/module-msrp-sample-data:100.1.0 magento/module-configurable-sample-data:100.1.0 magento/module-product-links-sample-data:100.1.0 magento/module-wishlist-sample-data:100.1.0 magento/module-swatches-sample-data:100.1.0 magento/sample-data-media:100.1.0 magento/module-offline-shipping-sample-data:100.1.0 magento/module-gift-card-sample-data:100.1.0 magento/module-customer-balance-sample-data:100.1.0 magento/module-target-rule-sample-data:100.1.0 magento/module-gift-registry-sample-data:100.1.0 magento/module-multiple-wishlist-sample-data:100.1.0 --no-update
      

To upgrade to a Release Candidate, append -rc<x> to the version of each module. For example, -rc3.

  1. Update dependencies:
    1
    
    composer update
    
  2. If prompted, enter your authentication keys.
  3. Wait for dependencies to update.

Finish your upgrade

After you have reset file system permissions:

  1. If you haven’t done so already, log in to your Magento server as, or switch to, the Magento file system owner.
  2. Change to your Magento installation directory.
  3. Manually clear the var/cache, var/page_cache, and var/generation directories. A sample command follows:
    1
    
    rm -rf var/cache/* var/page_cache/* var/generation/*
    
  4. Upgrade Magento:
    1
    
    php bin/magento setup:upgrade
    

Apply file system permissions and ownership

As part of the sample data upgrade process, you must apply current file system permission and ownership as discussed in the following sections. Failure to do so will cause your upgrade to fail.

For more information about file system ownership and permissions, see Overview of ownership and permissions.

One-user ownership and permissions

If you run the Magento application as one user (which is typical of shared hosting environments), change file system permissions and ownership as follows:

1
cd <magento_root>
1
chmod -R g+w var vendor pub/static pub/media app/etc
1
chmod u+x bin/magento

To optionally enter all commands on one line, enter the following assuming Magento is installed in /var/www/html/magento2:

1
cd /var/www/html/magento2 && chmod -R g+w var vendor pub/static pub/media app/etc && chmod u+x bin/magento

After you set file system permissions, manually clear the var/cache, var/page_cache, and var/generation directories.

A sample command follows:

1
rm -rf var/cache/* var/page_cache/* var/generation/*

Two-user ownership and permissions

If you run the Magento application with two users, enter the following commands as a user with root privileges:

1
cd <magento_root>
1
find var vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
1
find var vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
1
chown -R :<web server group> .
1
chmod u+x bin/magento

To optionally enter all commands on one line, enter the following assuming Magento is installed in /var/www/html/magento2 and the web server group name is apache:

1
cd /var/www/html/magento2 && find var vendor pub/static pub/media app/etc -type f -exec chmod g+w {} + && find var vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} + && chown -R :apache . && chmod u+x bin/magento

Commerce only: Web Setup Wizard upgrade to Magento Commerce version 2.1 with sample data

Upgrades to Magento Commerce 2.1 with sample data can fail because of the following issues:

  • An issue with the Magento composer-installer component. It doesn’t correctly detect code changes and therefore doesn’t update the cache and compiled code directories properly. As a result, fatal errors display during the upgrade.

    We have a patch that resolves this issue.

  • Magento’s composer.lock file specifies a non-existent component type; this issue prevents the upgrade with sample data from completing successfully.

    You can edit composer.lock to fix this issue.

Get the patch

Use the following instructions to get the patch named MDVA-532.*, then transfer it to your Magento server.

To get the patch:

You can get a Magento Commerce patch in any of the following ways:

From the Magento Commerce merchant portal

To get a patch from the Magento Commerce merchant portal:

  1. Go to www.magento.com.
  2. In the top horizontal navigation bar, click My Account.
  3. Log in with your Magento username and password.
  4. In the left navigation bar, click Downloads.
  5. Click Magento Enterprise Edition > 2.X > Magento Enterprise Edition 2.x Release > Support Patches.
  6. Transfer the patch to your development system.

From the Magento Commerce partner portal

To get a patch from the Magento Commerce partner portal:

  1. Log in to partners.magento.com.
  2. Click Magento Enterprise Edition > Magento Enterprise Edition 2.X > Magento Enterprise Edition 2.x Release > Support Patches.
  3. In the left navigation bar, click Downloads.
  4. Follow the instructions on your screen to download the desired patch.
  5. Transfer the patch to your development system.

Apply the patch

As the Magento file system owner, extract the patch in your Magento installation directory.

To apply the patch:

To apply a patch:

  1. Copy the patch file to your Magento installation directory.
  2. As the Magento file system owner, use one of the following commands to extract it:
Patch file format Command to extract
.zip unzip -o <patch name>.zip
.tar.gz tar -zxf <patch name>.tar.gz
.tar.bz2 tar -jxf <patch name>.tar.bz2

If you don’t have command line access to your Magento server, extract the patch locally and transfer the files to the server using an FTP application.

For example, to change to the magento_user and extract MDVA-532.zip into /var/www/magento2, enter:

1
su magento_user && cd /var/www/magento2 && unzip MDVA-532.zip

Fix composer.lock

To fix composer.lock:
  1. As the Magento file system owner, open <magento_root>/composer.lock in a text editor.
  2. Change the following entry.

    from:

    1
    
    "type": "magento2-module-customer-balance",
    

    to:

    1
    
    "type": "magento2-module",
    
  3. Save your changes to composer.lock and exit the text editor.

Manually clear directories

Manually clear the var/cache, var/page_cache, and var/generation directories.

A sample command follows:

1
rm -rf var/cache/* var/page_cache/* var/generation/*

Start the upgrade

Start your upgrade as discussed in Start System Upgrade.

Updated