Before you begin
You must complete the upgrade prerequisites to prepare your environment before starting the upgrade process.
Manage packages
-
Switch to maintenance mode to prevent access to your store during the upgrade process.
bin/magento maintenance:enable
See Enable or disable maintenance mode for additional options. Optionally, you can create a custom maintenance mode page.
-
Starting the upgrade process while asynchronous processes, such as message queue consumers, are running may cause data corruption. To prevent data corruption, disable all cron jobs.
Adobe Commerce on cloud infrastructure:
./vendor/bin/ece-tools cron:disable
Magento Open Source:
bin/magento cron:remove
-
Start all message queue consumers manually to ensure that all messages are consumed.
bin/magento cron:run --group=consumers
Wait for the cron job to complete. You can monitor the status of the job with a process viewer or by running the
ps aux | grep 'bin/magento queue'
command multiple times until all processes complete. -
Create a backup of the
composer.json
file.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 Adobe Commerce, remove the Magento Open Source package.
composer remove magento/product-community-edition --no-update
You can also upgrade sample data.
composer require <sample data module-1>:<version> ... <sample data module-n>:<version> --no-update
-
Adobe Commerce:
composer require magento/module-bundle-sample-data:100.4.* magento/module-widget-sample-data:100.4.* magento/module-theme-sample-data:100.4.* magento/module-catalog-sample-data:100.4.* magento/module-customer-sample-data:100.4.* magento/module-cms-sample-data:100.4.* magento/module-catalog-rule-sample-data:100.4.* magento/module-sales-rule-sample-data:100.4.* magento/module-review-sample-data:100.4.* magento/module-tax-sample-data:100.4.* magento/module-sales-sample-data:100.4.* magento/module-grouped-product-sample-data:100.4.* magento/module-downloadable-sample-data:100.4.* magento/module-msrp-sample-data:100.4.* magento/module-configurable-sample-data:100.4.* magento/module-product-links-sample-data:100.4.* magento/module-wishlist-sample-data:100.4.* magento/module-swatches-sample-data:100.4.* magento/sample-data-media:100.4.* magento/module-offline-shipping-sample-data:100.4.* magento/module-gift-card-sample-data:100.4.* magento/module-customer-balance-sample-data:100.4.* magento/module-target-rule-sample-data:100.4.* magento/module-gift-registry-sample-data:100.4.* magento/module-multiple-wishlist-sample-data:100.4.* --no-update
-
Magento Open Source:
composer require magento/module-bundle-sample-data:100.4.* magento/module-widget-sample-data:100.4.* magento/module-theme-sample-data:100.4.* magento/module-catalog-sample-data:100.4.* magento/module-customer-sample-data:100.4.* magento/module-cms-sample-data:100.4.* magento/module-catalog-rule-sample-data:100.4.* magento/module-sales-rule-sample-data:100.4.* magento/module-review-sample-data:100.4.* magento/module-tax-sample-data:100.4.* magento/module-sales-sample-data:100.4.* magento/module-grouped-product-sample-data:100.4.* magento/module-downloadable-sample-data:100.4.* magento/module-msrp-sample-data:100.4.* magento/module-configurable-sample-data:100.4.* magento/module-product-links-sample-data:100.4.* magento/module-wishlist-sample-data:100.4.* magento/module-swatches-sample-data:100.4.* magento/sample-data-media:100.4.* magento/module-offline-shipping-sample-data:100.4.* --no-update
-
-
Upgrade your instance using the following
composer require-commerce
command syntax:composer require-commerce magento/<product> <version> --no-update [--interactive-root-conflicts] [--force-root-updates] [--help]
Command options include:
-
<product>
—(Required) The package to upgrade. For on-premises installations, this value must be eitherproduct-community-edition
orproduct-enterprise-edition
. -
<version>
—(Required) The version of Adobe Commerce that you are upgrading to. For example,2.4.3
. -
--no-update
—(Required) Disables the automatic update of the dependencies. -
--interactive-root-conflicts
—(Optional) Allows you to interactively view and update any out-of-date values from previous versions, or any customized values that do not match the version you are upgrading to. -
--force-root-updates
—(Optional) Overrides all conflicting custom values with the expected Commerce values. -
--help
—(Optional) Provides usage details about the plugin.
If neither
--interactive-root-conflicts
nor--force-root-updates
are specified, the command keeps the existing values that are in conflict and displays a warning message. To learn more about the plugin, refer to the Plugin Usage README. -
-
Update the dependencies.
composer update
Example - list available versions
To see the full list of available 2.4.x versions:
Magento Open Source:
composer show magento/product-community-edition 2.4.* --available | grep -m 1 versions
Adobe Commerce:
composer show magento/product-enterprise-edition 2.4.* --available | grep -m 1 versions
Example - Quality patch
Quality patches primarily contain functional and security fixes. However, they can sometimes contain new, backward-compatible features. Use Composer to download a quality patch.
Adobe Commerce:
composer require-commerce magento/product-enterprise-edition 2.4.6 --no-update
Magento Open Source:
composer require-commerce magento/product-community-edition 2.4.6 --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.4.x-px
.
Adobe Commerce:
composer require-commerce magento/product-enterprise-edition 2.4.6-p3 --no-update
Magento Open Source:
composer require-commerce magento/product-community-edition 2.4.6-p3 --no-update
Update metadata
-
Update the
"name"
,"version"
, and"description"
fields in thecomposer.json
file as needed.NOTE
Updating the metadata in thecomposer.json
file is entirely superficial, not functional. -
Apply updates.
composer update
-
Clear the
var/
andgenerated/
subdirectories:rm -rf var/cache/*
rm -rf var/page_cache/*
rm -rf generated/code/*
NOTE
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.
bin/magento setup:upgrade
-
Disable maintenance mode.
bin/magento maintenance:disable
-
(Optional) Restart Varnish.
If you use Varnish for page caching, restart it:
service varnish restart
Check your work
To check whether the upgrade was successful, open your storefront URL in a web browser. If your upgrade was unsuccessful, your storefront does 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
root
privileges. -
Clear the following directories:
var/cache/
var/page_cache/
generated/code/
-
Check your storefront in your web browser again.