How We Handle Magento 2 Version Upgrades

At CustomGento, we work with Magento 2 shops every day. To keep these shops stable, secure, and up to date, we regularly perform updates. While security patches are important, sometimes stores need a proper version upgrade, for example from Magento 2.4.6 to 2.4.9.

These upgrades typically improve performance, add new features, and fix security issues. However, they can also introduce breaking changes that affect custom modules, themes, and third-party extensions.

That’s why we don’t just click “update” and hope for the best. Instead, we follow a clear and well-structured process that helps us avoid these issues.

Here’s a quick look at how we handle a full Magento 2 version upgrade.

Preparation

Before updating anything, we need to make sure everything is properly prepared. One of the most important tools we use when upgrading Magento is the Magento 2 Upgrade GUI by elgentos, so we need to make sure it’s present on our system. This handy tool allows us to visually spot differences in a three-way comparison between the original version, the new one, and the custom preferences, plugins, and template overrides.

We also temporarily clone the Ampersand Upgrade Patch Helper into the project root, since we only need it for the duration of the upgrade. This tool will later help us identify which of our overrides need adjustments based on the changes in the new Magento version.

The Magento Core Update

After we’ve set up the basics, we’re ready to begin the update.

First of all, we check out the main branch and run composer install to make sure our local environment matches production. Then, we copy the original vendor folder so we can compare it with the new version later.

Next, we create a dedicated branch just for the Magento version update. In the root composer.json file we check if the magento/composer-root-update-plugin is installed and up to date. This Composer plugin is essential, because it helps manage changes in the composer.json during the upgrade.

With everything ready, we require the new Magento version via Composer.

Sometimes our own modules have strict dependency rules, which can lead to conflicts. In those cases, we temporarily remove dependencies, perform the upgrade, and then reintroduce and test them one by one. We always keep at least one older version as a fallback, so we can go back to a working state if needed.

Once the upgrade is done, we manually update the Magento version in composer.json, run composer update to apply all minor package updates, and use composer outdated to check if there are any remaining version bumps that need to be handled manually.

We also go through any third-party extensions with limited update periods. Since Composer won’t show these as outdated, we compare the currently installed version with the latest version on the vendor’s product page. If the update period has ended and there’s a relevant update available, we talk to the client about extending the license.

After that, we compare the old and new vendor folders to generate a diff file. Using the Ampersand Patch Helper, we analyze the diff and generate a classmap that is required for the Magento 2 Upgrade GUI. This helps us see exactly where we need to update or remove custom overrides.

Reviewing Overrides and Dependencies

Using the GUI, we review all relevant files. This includes theme files, email templates, and anything marked with a “based on” comment in PHTML files, which indicates that it depends on a Magento core file.

Next, we run composer audit and check whether previously ignored audit issues can now be removed from the root composer.json.

With the update nearly complete, we run the usual commands: setup:upgrade, setup:di:compile, and setup:static-content:deploy to verify that everything compiles and builds correctly.

Finally, we check whether the update has modified our .gitignore file. If so, we manually adjust it so that we aren’t accidentally committing files we shouldn’t. The test configuration files, like the project-specific PHPUnit XML configs, also need to be compared with the new base files and updated if needed.

We also update all Node packages across the project, keeping in mind that there might be multiple package.json files, for example in the root directory and in the theme directories.

Once everything passes, we open a pull request that includes the complete upgrade: the Magento core update along with all extension and dependency updates.

Testing the Upgrade

Before we consider the upgrade done, we thoroughly test the shop. This includes creating a test order, testing account creation and login, and going through every major page type: the homepage, category pages, product pages, the cart, checkout, CMS pages, and the site imprint. We compare each page between the live shop and the local environment to spot any visual or functional differences.

If the project has a specific testing checklist, we go through that as well. We also run our static checks: PHPStan, PHP_CodeSniffer with the Magento coding standard, and the Yireo Extension Checker, which makes sure our own modules declare all of their dependencies. On top of that, we run the automated test suites — unit tests, integration tests, and any end-to-end tests using MFTF, Cypress, or Playwright — before passing the update on for review.

Final Steps After Deployment

After deploying the update to the store, we update the Varnish configuration.

As a last step, we clean up by removing the temporary files and folders that were only needed during the upgrade, like the Ampersand Patch Helper and the copied vendor directory.

Why This Matters

Upgrading Magento isn’t just about using the latest version — it’s about keeping your store healthy, secure, and ready for whatever comes next. By following this structured process, we make sure that every update is deployed smoothly without breaking any existing functionality.

Also, we don’t do all of this by hand anymore. Many of the steps are now carried out by AI, like updating third-party extensions to their latest versions, restoring the dependencies of our own modules, and adapting our customizations to the changes in the new Magento version. One of our developers reviews every change, and anything that needs a judgment call, like resolving conflicts or testing the shop, stays in human hands.

If you’re running a Magento 2 store and wondering when or how to upgrade, feel free to reach out. We’d love to help.