Important

You are browsing documentation for version 5.1 of OroCommerce, supported until March 2026. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Upgrade the Application to the Next Version

This guide explains how to upgrade Oro application to the next version in a development environment.

An absolute path to the directory where an application is installed will be used in the guide and will be referred to as <application-root-folder> further in this topic.

Note

We highly recommend running all the commands in this guide from the same user the web server runs (e.g., nginx or www-data).

To retrieve a new version and upgrade your Oro application instance, execute the following steps:

Navigate to the Oro application root folder.
```
cd <application-root-folder>
```
Make sure that no changes require the database schema update.
```
php bin/console oro:entity-extend:update --dry-run --env=prod
```
The platform update is possible only when the database schema is up-to-date.

Switch the application to maintenance mode.

php bin/console lexik:maintenance:lock --env=prod

Stop the cron tasks.

crontab -e

Comment this line.

*/1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null

Stop all running consumers.
Create backups of your Database and Code.
Get changes.

If You Checkout from the GitHub Repository:

Pull changes from the Oro application GitHub repository.
- Add the corresponding ORO application repository as an additional remote by running one of commands below. In the example the new remote name is oro.
```
# OroCommerce Community Edition
git remote add oro git@github.com:oroinc/orocommerce-application.git
# OroCommerce Enterprise Edition
git remote add oro git@github.com:oroinc/orocommerce-enterprise-application.git
# OroCRM Community Edition
git remote add oro git@github.com:oroinc/crm-application.git
# OroCRM Enterprise Edition
git remote add oro git@github.com:oroinc/crm-enterprise-application.git
# OroPlatform Community Edition
git remote add oro git@github.com:oroinc/platform-application.git
# OroCommerce Community Edition for Germany
git remote add oro git@github.com:oroinc/orocommerce-application-de.git
# OroCommerce Enterprise Edition for Germany
git remote add oro git@github.com:oroinc/orocommerce-enterprise-application-de.git
# OroCommerce Enterprise Edition (without CRM)
git remote add oro git@github.com:oroinc/orocommerce-enterprise-nocrm-application.git
```
- Fetch tags from the corresponding ORO application repository
```
git fetch oro --tags
```
- Checkout the new branch that will contain the code of the upgraded application to the next version
```
git checkout -b feature/upgrade
```
- Merge changes from the corresponding ORO application repository to the new branch
```
git merge 5.0.7 --allow-unrelated-histories
```
  Replace 5.0.7 with the version you upgrade the application to.
- Resolve conflicts if needed and commit changes
  Note
  If you have any customization or third-party extensions installed, make sure that:
  your changes to the src/AppKernel.php file are merged to the new file.
  
  your changes to the src/ folder are merged, and it contains the custom files.
  
  your changes to the composer.json file are merged into the new file.
  
  your changes to the packages.json file are merged to the new file.
  
  your changes to configuration files in the config/ folder are merged to the new files.
```
git commit
```
If You Download the Source Code Archive:

Download the latest version of the application source code from the download section on the website:
Note
If you have any customization or third-party extensions installed, make sure that:
- your changes to the src/AppKernel.php file are merged to the new file.
- your changes to the src/ folder are merged, and it contains the custom files.
- your changes to the composer.json file are merged into the new file.
- your changes to the packages.json file are merged to the new file.
- your changes to configuration files in the config/ folder are merged to the new files.
Remove old caches.
```
rm -rf var/cache/prod/
```
Set up your project source code with Composer.
```
composer install --prefer-dist --no-dev
```
Refer to the UPGRADE.md and CHANGELOG.md files in the application repository for a list of changes in the code that may affect the upgrade of some customizations.
Upgrade the platform.
```
php bin/console oro:platform:update --env=prod
```
Note

To speed up the update process, consider using --schedule-search-reindexation or --skip-search-reindexation option:
- --schedule-search-reindexation — postpone search reindexation process until the message queue consumer is started (on step 12 below).
- --skip-search-reindexation — skip search reindexation. Later, you can start it manually using commands oro:search:reindex to update search index for the specified entities and oro:website-search:reindex to rebuild storefront search index. See Search Index: Indexation Process.
Note

When the following options are not provided, they are set up automatically for the test environment:
- –force
- –skip-translations
- –timeout=600
The verbose mode is always set to debug in the test environment.

Remove the caches.

php bin/console cache:clear --env=prod

or, as an alternative:

rm -rf var/cache/prod/
php bin/console cache:warmup --env=prod

Enable cron.

crontab -e

Uncomment this line.

*/1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null

Switch your application back to the normal mode from the maintenance mode.
```
php bin/console lexik:maintenance:unlock --env=prod
```
Run the consumer(s).
```
php bin/console oro:message-queue:consume --env=prod
```
Note

If PHP bytecode cache tools (e.g., opcache) are used, PHP-FPM (or Apache web server) should be restarted after the upgrade to flush cached bytecode from the previous installation.

See Also

Deploy Application Changes to a New Environment (Testing or Production).

Business Tip

Looking to harness the new trend of digital commerce? Check out our guide on a B2B marketplace platform.