How do I upgrade a heavily customised Magento 2 store?

To upgrade a customised Magento 2 store, audit every customisation first, then run the upgrade on a staging copy. Fix conflicts in order of risk, starting with core class preferences, and deploy only once the copy passes regression testing. The Composer commands take minutes. Most of the effort goes into finding custom code that relies on core classes Adobe has since changed.

This guide covers upgrades within Magento 2, such as Magento 2.4.5 to 2.4.9. Moving from Magento 1 is a full migration and needs a different plan.

How to upgrade a customised Magento 2 store, step by step

1. Audit every custom module and core override

List everything that sits between you and a clean core. Check these places:

• Custom modules in app/code, especially any that declare a preference for a core class in di.xml.
• Third-party extensions in composer.json and app/code, with the vendor and installed version of each.
• Core patches applied through cweagans/composer-patches or copied into the codebase by hand.
• Theme template and layout overrides of core modules in app/design.
• Integrations with ERP, PIM, payment, and shipping systems.

This inventory becomes your upgrade checklist. Anything missing from it tends to surface later as a production bug.

2. Choose the target Magento version and server stack

Pick the version you are moving to before you touch any code. Magento 2.4.9 is the current release. Check its PHP, MySQL or MariaDB, OpenSearch, and Composer versions on Adobe’s system requirements page.

According to Adobe’s upgrade prerequisites, Magento 2.4.8 and later no longer support Elasticsearch. Stores still on it must switch to OpenSearch first. If you are on Magento 2.4.5, you are running PHP 8.1, which 2.4.9 no longer supports. Magento 2.4.9 also moves Symfony dependencies to the 7.4 LTS line, according to Adobe’s release notes. Custom classes that extend Symfony core classes need updated type declarations and method signatures as a result.

3. Scan custom code for Magento 2 upgrade conflicts

Pick the scan tool that matches your edition:

The Upgrade Compatibility Tool requires an Adobe Commerce license, so it does not cover Magento Open Source. Compilation errors point straight at broken DI wiring, so run setup:di:compile on the target version whichever edition you use. In parallel, ask each extension vendor for a release that supports your target version.

4. Upgrade a staging clone, never production

Clone the store with a recent copy of the production database and media. Then update the version constraint and dependencies with Composer:

composer require-commerce magento/product-community-edition 2.4.9 --no-update
composer update
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy

Swap in the latest 2.4.9 patch release (2.4.9-pN) available when you start. Adobe Commerce stores use magento/product-enterprise-edition instead. The require-commerce command comes from magento/composer-root-update-plugin. Expect the first composer update to fail with dependency conflicts. Each conflict names the package blocking the upgrade.

5. Fix conflicts in order of risk

Work through the conflicts from the code scan and the failed composer update, most dangerous first:

1. Preferences on core classes: these replace core code completely, so they break hardest. Convert them to plugins where you can.
2. Plugins and observers: confirm the methods and events they hook still exist with the same signatures.
3. Core patches: drop patches the new version already includes and rebase the rest.
4. Theme overrides: diff each overridden template against the new core file and port your changes.
5. Abandoned extensions: replace or remove any extension without a compatible release.

6. Regression test checkout and integrations

Test the flows where a failure costs most: product pages, cart, checkout, every payment method, shipping rates, order emails, and admin order handling. Each integration needs its own end-to-end test, including order export, stock sync, and product feeds. If you have a Playwright or Cypress suite, run it against staging. Follow it with one manual order per payment method. A test can pass while a real card payment still fails at the gateway.

7. Plan the customised Magento 2 upgrade cutover and rollback

Freeze code and catalogue changes before release. Take a full database and code backup, deploy in a maintenance window, and tag the previous release so you can roll back fast. For the first few days, watch var/log/exception.log and system.log. Compare hourly orders and payment failures against the same days last week.

The customisation audit decides how hard your customised Magento 2 upgrade will be. Plugins break only when the method they wrap changes, while preferences break whenever the class they replace changes. That difference decides most of the refactoring effort. Our Magento development team can run that audit for you and flag which customisations will need rework.