You can upgrade your Magento application from the command line if you installed the software by:
- Downloading the metapackage using
- Installing the compressed archive.
Do not use this method to upgrade if you cloned the Magento 2 GitHub repository. Instead, see Update the Magento application for upgrade instructions.
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—See Modify docroot to improve security for more details.
- 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:
See Enable or disable maintenance mode for additional options.
Optionally, you can create a custom maintenance mode page.
Using the more manual process of upgrading via the command line allows you to track and control exactly what is being changed in the upgrade.
See the examples at the end of this section for help specifying different release levels. For example, minor release, quality patch, and security patch. Magento Commerce customers can access 2.3.x patches two weeks before the General Availability (GA) date. Pre-release packages are available through Composer only. You cannot find them on the Magento Portal or GitHub until GA. If you cannot find these packages in Composer, contact Magento Support.
cp composer.json composer.json.bak
Add or remove specific packages based on your needs. For example, if you are upgrading from Magento Open Source to Magento Commerce, remove the Magento Open Source package.
composer remove magento/product-community-edition --no-update
Indicate the Magento packages, both the edition (
enterprise) and the version (
2.3.3), that you want to upgrade to.
Magento Open Source:
composer require magento/product-community-edition=2.3.3 --no-update
composer require magento/product-enterprise-edition=2.3.3 --no-update
To see the full list of available 2.3 versions:
Magento Open Source:
composer show magento/product-community-edition 2.3.* --all | grep -m 1 versions
composer show magento/product-enterprise-edition 2.3.* --all | grep -m 1 versions
Specify additional packages.
composer require --dev allure-framework/allure-phpunit:~1.2.0 friendsofphp/php-cs-fixer:~2.14.0 lusitanian/oauth:~0.8.10 magento/magento-coding-standard:~3.0.0 magento/magento2-functional-testing-framework:2.4.5 pdepend/pdepend:2.5.2 phpmd/phpmd:@stable phpunit/phpunit:~6.5.0 sebastian/phpcpd:~3.0.0 squizlabs/php_codesniffer:~3.4.0 --sort-packages --no-update
Remove unused packages.
If you are upgrading from 2.2.x to 2.3.x, remove unused packages with the following command. It is not needed if you are upgrading from 2.3.x.
composer remove --dev sjparkinson/static-review fabpot/php-cs-fixer --no-update
Example - Minor release
Minor releases contain new features, quality fixes, and security fixes. Use Composer to specify a minor release. For example, to specify the Magento Commerce 2.3.0 metapackage:
1 composer require magento/product-community-edition=2.3.0 --no-update
Example - Quality patch
Quality patches primarily contain functional and security fixes. However, they can also sometimes contain new, backward-compatible features. Use Composer to download a quality patch. For example, to specify the Magento Commerce 2.3.3 metapackage:
1 composer require magento/product-community-edition=2.3.3 --no-update
Example - Security patch
Security patches contain security fixes only. They are designed to make the upgrade process faster and easier.
Security patches use the Composer naming convention
2.3.3-px. Use Composer to specify a patch. For example, to download the Magento Open Source 2.3.3-p1 metapackage:
1 composer require magento/product-community-edition=2.3.3-p1 --no-update
(Optional) Recreate the Magento updater
If the Magento updater is installed, remove and recreate it. It is located in the
Create a Composer project.
Magento Open Source version 2.3.3:
composer create-project --repository=https://repo.magento.com magento/project-community-edition=2.3.3 temp_dir --no-install
Magento Commerce version 2.3.3:
composer create-project --repository=https://repo.magento.com magento/project-enterprise-edition=2.3.3 temp_dir --no-install
If you need to use a repository that contains non-public packages, such as internal sandboxes, change the URL in
Remove the old
update/directory and move
rm -rf update
mv temp_dir/update .
rm -rf temp_dir
"description"fields in the
composer.jsonfile as needed.
Updating the metadata in
composer.jsonfile is entirely superficial, not functional.
Clean the Magento cache.
Manually clear caches and generated content.
rm -rf var/cache/*
rm -rf var/page_cache/*
rm -rf 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.
Disable maintenance mode.
(Optional) Restart Varnish.
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:
- Reset file system ownership and permissions as a user with
- Clear the following directories:
- Check your storefront in your web browser again.
There are alternatives methods that automate parts of the upgrade process:
- Upgrade using the script (semi-automated process). We recommend using the script to upgrade if you have not made updates to the values that the script affects. If you previously made updates, do not upgrade using the script. The script will override your updates.
- Upgrade using the custom Composer plugin. We created a custom Composer plugin to enhance the semi-automated upgrade process.
The upgrading scenario is the same for each of these options. Both use Composer and a command line interface.
All scenarios require that you comply with the Prerequisites.