Command-line upgrade

You can upgrade Magento from the command line if you installed the software by:

  • Downloading the metapackage using composer create-project.
  • Installing the compressed archive.

There are two ways to upgrade your Magento application to the 2.3 version:

  1. Upgrade using the command line (manual process)
  2. Upgrade using the script (semi-automated process)

The upgrade scenario is the same for each of these options (both utilize Composer and a command line interface) from the system’s point of view. However, if you upgrade using the script several of the steps are automated.

Both scenarios require that you comply with the Prerequisites.

If you cloned the Magento 2 GitHub repository, you cannot use this method to upgrade. Instead, see Update the Magento application for upgrade instructions.

Prerequisites

Complete the following prerequisites to prepare your environment before starting the upgrade process:

  • Complete the Update and upgrade checklist—To avoid possible errors during installation or upgrading, complete the Update and upgrade checklist.
  • Set the pub directory root—If you set the Magento root directory to <your Magento install dir>/pub, create another subdomain or docroot that uses the Magento installation directory as its root, and run the System Upgrade utility using that subdomain.
  • Check PHP and environment settings—Verify that your PHP and other environment settings are compatible with the system requirements.
  • Switch to maintenance mode—To prevent access to your store while it’s being upgraded, switch your store to maintenance mode:

      php <your Magento install dir>/bin/magento maintenance:enable
    

    See Enable or disable maintenance mode for additional options.

    Optionally, you can create a custom maintenance mode page.

Upgrade using the command line

Using the more manual process of upgrading via the command line allows you to track and control exactly what’s being changed in the upgrade. If you previously made updates to the same values that the upgrade script affects, the script will override those values, so using the manual process is the best approach. Upgrading using the script process is a bit easier and less intensive, if you have not made updates to values that the script affects.

Backup composer.json

Backup the existing composer.json file in the Magento installation directory.

Manage packages

Specify needed packages and remove any unneeded ones before proceeding with the upgrade.

Deactivate the Magento Open Source update

Optional—If you are upgrading from Magento Open Source to Magento Commerce, deactivate the Magento Open Source update:

composer remove magento/product-community-edition --no-update

Specify Magento packages

Indicate the Magento packages, both the edition (community or enterprise) and the version (2.3.0), that you want to upgrade to.

Magento Open Source

composer require magento/product-community-edition=2.3.0 --no-update

Magento Commerce

composer require magento/product-enterprise-edition=2.3.0 --no-update

To see a full list of available 2.3 versions:

Magento Open Source

composer show magento/product-community-edition 2.3.* --all | grep -m 1 versions

Magento Commerce

composer show magento/product-enterprise-edition 2.3.* --all | grep -m 1 versions

Specify additional packages

composer require --dev phpunit/phpunit:~6.2.0 friendsofphp/php-cs-fixer:~2.10.1 lusitanian/oauth:~0.8.10 pdepend/pdepend:2.5.2 sebastian/phpcpd:~3.0.0 squizlabs/php_codesniffer:3.2.2 --no-update

Remove unused packages

composer remove --dev sjparkinson/static-review fabpot/php-cs-fixer --no-update

Update autoload

Open composer.json and edit the "autoload": "psr-4" section to include "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/":

"autoload": {
    "psr-4": {
        "Magento\\Framework\\": "lib/internal/Magento/Framework/",
        "Magento\\Setup\\": "setup/src/Magento/Setup/",
        "Magento\\": "app/code/Magento/",
        "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
    },
    ...
}

Modify the Magento updater

Optional—If the Magento updater is installed (it is located in <Magento install dir>/update) modify it:

  1. Backup and remove the old updater, in the <Magento install dir>/update directory.
  2. Create a Composer project.

    Magento Open Source version 2.3.0:

     composer create-project --repository=https://repo.magento.com magento/project-community-edition=2.3.0 temp_dir --no-install
    

    Magento Commerce version 2.3.0:

     composer create-project --repository=https://repo.magento.com magento/project-enterprise-edition=2.3.0 temp_dir --no-install
    

    If you need to use a repository that contains non-public packages, such as internal sandboxes, change the URL in --repository accordingly.

  3. Move the project to the <Magento install dir>/update directory:

    mkdir update
    
    mv temp_dir/update <Magento install dir>/update
    
    rm -rf temp_dir
    

Update metadata

Update the "name", "version", and "description" fields in the <Magento install dir>/composer.json file as desired.

Updating the metadata in composer.json file is entirely superficial, not functional.

Apply updates

composer update

Clear caches and generated content

Clear the var and generated subdirectories:

rm -rf <Magento install dir>/var/cache/*
rm -rf <Magento install dir>/var/page_cache/*
rm -rf <Magento install dir>/generated/code/*

If you use a cache storage other than the filesystem, such as Redis or Memcached, you must manually clear the cache there too.

Update the database schema and data

php bin/magento setup:upgrade

Disable maintenance mode

php bin/magento maintenance:disable

Restart Varnish

Optional—If you use Varnish for page caching, restart it:

service varnish restart

Check your work

Open your storefront URL in a web browser to check whether the upgrade was successful. If your upgrade was unsuccessful, your storefront will not load properly.

If the application fails with a We're sorry, an error has occurred while generating this email. error:

  1. Reset file system ownership and permissions as a user with root privileges.
  2. Clear these directories:
    • <your Magento install dir>/var/cache
    • <your Magento install dir>/var/page_cache
    • <your Magento install dir>/generated/code
  3. Check your storefront in your web browser again.

Upgrade using the script

Upgrading your Magento installation with our script, which makes the upgrade process semi-automated, is the preferred method—it’s easy, quick, and efficient.

Run this script after upgrading to PHP 7.1 or 7.2.

If you previously made updates to the same values that the upgrade script affects, the script will override those values, so using the manual process is the best approach.

The upgrade script:

  • Updates Magento with the 2.3 requirements.
  • Backs up the composer.json file.
  • Specifies the new version of the Magento metapackage.
  • Updates the "require-dev" section in the composer.json file.
  • Adds "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/" to the "autoload":"psr-4" section in the composer.json file.
  • Backs up and updates the magento/updater, if it has been installed.
  • Updates the "name", "version", and "description" fields in the composer.json file.

Download the script

Download, or copy, the script file from the magento/magento2 repo, /dev/tools/UpgradeScripts/pre_composer_update_2.3.php.

Show script options

php -f pre_composer_update_2.3.php -- --help

Run the script

php -f pre_composer_update_2.3.php -- --root='<path/to/magento/install/dir>' --repo=https://repo.magento.com/ <options>

Apply updates

composer update

Clear caches and generated content

Clear the var and generated subdirectories:

rm -rf <Magento install dir>/var/cache/*
rm -rf <Magento install dir>/var/page_cache/*
rm -rf <Magento install dir>/generated/code/*

If you use a cache storage other than the filesystem, such as Redis or Memcached, you must manually clear the cache there too.

Update the database schema and data

php bin/magento setup:upgrade

Disable maintenance mode

php bin/magento maintenance:disable

Restart Varnish

Optional—If you use Varnish for page caching, restart it:

service varnish restart

Check your work

Open your storefront URL in a web browser to check whether the upgrade was successful. If your upgrade was unsuccessful, your storefront will not load properly.

If the application fails with a We're sorry, an error has occurred while generating this email. error:

  1. Reset file system ownership and permissions as a user with root privileges.
  2. Clear these directories:
    • <your Magento install dir>/var/cache
    • <your Magento install dir>/var/page_cache
    • <your Magento install dir>/generated/code
  3. Check your storefront in your web browser again.