It is important to understand what is necessary to run Adobe Commerce or Magento Open Source. You must first review the system requirements for the version you are planning to upgrade to.
After reviewing system requirements, you must complete the following prerequisites before upgrading your system:
The system requirements describe exactly which versions of third-party software have been tested with Adobe Commerce and Magento Open Source releases.
For Adobe Commerce on cloud infrastructure Pro projects, you must create a Support ticket to install or update services in Staging and Production environments. Indicate the service changes needed and include your updated
services.yaml files and PHP version in the ticket. It can take up to 48 hours for the Cloud infrastructure team to update your project. See Supported software and services.
Adobe Commerce and Magento Open Source require Elasticsearch or OpenSearch to be installed in order to use the software.
If you are upgrading from 2.3.x to 2.4, you must check whether you are using MySQL, Elasticsearch, or a third-party extension as your catalog search engine in your 2.3.x instance. The result determines what you must do before upgrading to 2.4.
If you are upgrading patch releases within the 2.3.x or 2.4.x release lines, if Elasticsearch 7.x is already installed, you can optionally migrate to OpenSearch.
You can use the command line or the Admin to determine your catalog search engine:
bin/magento config:show catalog/search/engine command. The command returns a value of
elasticsearch (which indicates Elasticsearch 2 is configured),
elasticsearch7, or a custom value, indicating you have installed a third-party search engine. A value of
elasticsearch7 indicates that either Elasticsearch 7 or OpenSearch is installed.
From the Admin, check the value of the Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine field.
The following sections describe what actions that you must take before upgrading to 2.4.0.
As of 2.4, MySQL is no longer a supported catalog search engine. You must install and configure Elasticsearch or OpenSearch before upgrading. Use the following resources to help guide you through this process:
Some third-party catalog search engines run on top of the Adobe Commerce search engine. Contact your vendor to determine whether you must update your extension.
You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. Adobe no longer supports Elasticsearch 2.x, 5.x, and 6.x.
Refer to Upgrading Elasticsearch for full instructions on backing up your data, detecting potential migration issues, and testing upgrades before deploying to production. Depending on your current version of Elasticsearch, a full cluster restart may or may not be required.
Elasticsearch requires Java Development Kit (JDK) 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.
Configure Elasticsearch describes the tasks you must perform after updating Elasticsearch 2 to a supported version.
OpenSearch is an open-source fork of Elasticsearch 7.10.2, following Elasticsearch’s licensing change. The following releases of Adobe Commerce and Magento Open Source introduce support for OpenSearch:
You can migrate from Elasticsearch to OpenSearch only if you are upgrading to a version of Adobe Commerce or Magento Open Source listed above (or higher).
OpenSearch requires JDK 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.
Search engine configuration describes the tasks that you must perform after changing search engines.
We recommend that you contact your search engine vendor to determine whether your extension is fully compatible with 2.4.
You must convert the format of all database tables from
DYNAMIC. You must also convert the storage engine type from
InnoDB. See best practices.
Setting the open files limit (ulimit) can help avoid failure from multiple recursive calls of long query strings or issues with using the
bin/magento setup:rollback command. This command is different for different UNIX shells. Consult your individual flavor for specifics about the
Adobe recommends setting the open files ulimit to a value of
65536 or more, but you can use a larger value if necessary. You can set the ulimit on the command line or you can make it a permanent setting for the user’s shell.
To set the ulimit from the command line:
Switch to the file system owner.
Set the ulimit to
ulimit -n 65536
To set the value in your Bash shell:
Switch to the file system owner.
/home/<username>/.bashrc in a text editor.
Add the following line:
ulimit -n 65536
Save your changes to the
.bashrc file and exit the text editor.
We recommend that you avoid setting a value for the
pcre.recursion_limit property in the
php.ini file because it can result in incomplete rollbacks with no failure notice.
The UNIX task scheduler
cron is critical to day-to-day Adobe Commerce and Magento Open Source operations. It schedules things like reindexing, newsletters, e-mails, and sitemaps. Several features require at least one cron job running as the file system owner.
To verify that your cron job is set up properly, check the crontab by entering the following command as the file system owner:
The crontab is the configuration file responsible for running cron jobs.
Results similar to the following should display:
#~ MAGENTO START c5f9e5ed71cceaabc4d4fd9b3e827a2b * * * * * /usr/bin/php /var/www/html/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/html/magento2/var/log/magento.cron.log #~ MAGENTO END c5f9e5ed71cceaabc4d4fd9b3e827a2b
Another symptom of cron not running is the following error in the Admin:
To see the error, click System Messages at the top of the window as follows:
See Configure and run cron for more information.
Adobe Commerce 2.4 includes security enhancements that require some data to be converted from serialized to JSON. This conversion occurs during the upgrade and it can take a long time, depending on how much data is in your database.
The following tables are affected the most:
If you have a large amount of data, you can improve performance by setting the value of an environment variable,
DATA_CONVERTER_BATCH_SIZE. By default, the value is set to
To set the environment variable:
Switch to the file system owner.
Set the variable:
DATA_CONVERTER_BATCH_SIZE requires memory; avoid setting it to a large value (approximately 1 GB) without testing it first.
After your upgrade is complete, you can unset the variable:
For security reasons, Adobe Commerce and Magento Open Source require certain permissions on the file system. Permissions are different from ownership. Ownership determines who can perform actions on the file system; permissions determine what the user can do.
Directories in the file system must be writable by the file system owner’s group.
To verify that your file system permissions are set properly, either log into the application server or use your hosting provider’s file manager application.
For example, enter the following command if the application is installed in
ls -l /var/www/html/magento2
total 1028 drwxrwx---. 12 magento_user apache 4096 Jun 7 07:55 . drwxr-xr-x. 3 root root 4096 May 11 14:29 .. drwxrwx---. 4 magento_user apache 4096 Jun 7 07:53 app drwxrwx---. 2 magento_user apache 4096 Jun 7 07:53 bin -rw-rw----. 1 magento_user apache 439792 Apr 27 21:23 CHANGELOG.md -rw-rw----. 1 magento_user apache 3422 Apr 27 21:23 composer.json -rw-rw----. 1 magento_user apache 425214 Apr 27 21:27 composer.lock -rw-rw----. 1 magento_user apache 3425 Apr 27 21:23 CONTRIBUTING.md -rw-rw----. 1 magento_user apache 10011 Apr 27 21:23 CONTRIBUTOR_LICENSE_AGREEMENT.html -rw-rw----. 1 magento_user apache 631 Apr 27 21:23 COPYING.txt drwxrwx---. 4 magento_user apache 4096 Jun 7 07:53 dev -rw-rw----. 1 magento_user apache 2926 Apr 27 21:23 Gruntfile.js -rw-rw----. 1 magento_user apache 7592 Apr 27 21:23 .htaccess -rw-rw----. 1 magento_user apache 6419 Apr 27 21:23 .htaccess.sample drwxrwx---. 4 magento_user apache 4096 Jun 7 07:53 lib -rw-rw----. 1 magento_user apache 10376 Apr 27 21:23 LICENSE_AFL.txt -rw-rw----. 1 magento_user apache 30634 Apr 27 21:23 LICENSE_EE.txt -rw-rw----. 1 magento_user apache 10364 Apr 27 21:23 LICENSE.txt -rw-rw----. 1 magento_user apache 4108 Apr 27 21:23 nginx.conf.sample -rw-rw----. 1 magento_user apache 1427 Apr 27 21:23 package.json -rw-rw----. 1 magento_user apache 1659 Apr 27 21:23 .php_cs -rw-rw----. 1 magento_user apache 804 Apr 27 21:23 php.ini.sample drwxrwx---. 2 magento_user apache 4096 Jun 7 07:53 phpserver drwxrwx---. 6 magento_user apache 4096 Jun 7 07:53 pub -rw-rw----. 1 magento_user apache 2207 Apr 27 21:23 README_EE.md drwxrwx---. 7 magento_user apache 4096 Jun 7 07:53 setup -rw-rw----. 1 magento_user apache 3731 Apr 27 21:23 .travis.yml drwxrwx---. 7 magento_user apache 4096 Jun 7 07:53 update drwxrws---. 11 magento_user apache 4096 Jun 13 16:05 var drwxrws---. 29 magento_user apache 4096 Jun 7 07:53 vendor
See the following for an explanation of the sample output:
-rw-rw----, which is
To get more detailed information, you can enter the following command:
ls -la /var/www/html/magento2/pub
Because Adobe Commerce and Magento Open Source deploy static file assets to subdirectories of
pub, it’s a good idea to verify permissions and ownership there as well.
For more information, see File system permissions and ownership.
See Modify docroot to improve security for more details.
magento/composer-root-update-plugin Composer plugin resolves changes that must be made to the root project
composer.json file before updating to a new product requirement.
The plugin partially automates the manual upgrade by identifying and helping you resolve dependency conflicts instead of requiring you to identify and fix them manually.
To install the plugin:
Add the package to your
composer require magento/composer-root-update-plugin ~2.0 --no-update
Update the dependencies: