Magento 2 Upgrade Checklist for 2.4.x

A Magento 2 upgrade goes well when most of the work happens before the upgrade itself. Read the release notes, check the system requirements for the target version, audit every extension and customisation, rehearse on a copy of production, test the parts of the store that take money, and go live with a rollback you have already practised. Running Composer is the smallest part of the job.

This guide covers each stage in order and ends with a checklist you can copy.

Why upgrades get postponed, and why waiting costs more

An upgrade delivers nothing a customer will notice, so it loses to every trading priority.

The trouble is that the cost compounds. Each release you skip adds more change to absorb in one go: more deprecated code removed, more extension versions to jump, bigger differences in PHP and service versions. One release behind is a routine job. Several releases behind is a project.

There is also a deadline in the background. Adobe publishes a lifecycle policy with an end of support date for each release line. Once your version passes that date it stops receiving security fixes, and extension vendors tend to stop testing against it.

Security patches and full upgrades are different jobs

Security patch releases carry a -p suffix and contain security fixes for the release line you are already on. Apply them soon after release.
Full upgrades move you to a newer release in the 2.4 line. They bring quality fixes, platform changes and often new system requirements, and need the planning described here.

Do not hold security patches back so they can ride along with a larger upgrade. Patch promptly, and plan the upgrade as its own piece of work. A security patch still goes through staging and a checkout test first.

Start with the release notes and system requirements

Read the release notes for the target version and for every version in between. Look for backward incompatible changes, removed modules, changed defaults and known issues.

Then check infrastructure. The supported versions of PHP, MySQL or MariaDB, OpenSearch, Composer and the caching services change between Magento releases. Check Adobe’s system requirements page for your exact target version, not a version number quoted in an old article.

Two questions to answer early:

Can your hosting provide every required service version, and how much notice does the provider need?
Do your current and target Magento versions share a supported PHP version? If they do not, the infrastructure change and the code change have to land together, which makes the rehearsal more important.

Audit extensions and custom code

The Magento core usually upgrades cleanly. What breaks is what has been added to it.

Third-party extensions

List every installed module, from composer.json and from bin/magento module:status. For each one, ask:

Is it still used? If not, remove it before the upgrade. Every extension removed is one less thing to make compatible.
Has the vendor released a version that supports the target Magento version and the target PHP version?
Is the vendor still maintaining it at all? If not, plan a replacement now.
Was it installed through Composer, or copied into app/code? Copied extensions have to be updated by hand.

Custom modules and the theme

Your own code needs the same scrutiny. The usual trouble spots are plugins and preferences on core classes whose methods have changed, use of classes that are now deprecated or removed, and PHP code that does not run on the newer PHP version.

Themes are easy to forget. A template copied from a core module and overridden in the theme does not receive changes made to the original, so after an upgrade it can be quietly out of date.

Core modifications

Edits made directly to files under vendor/ are the most painful thing to find in an upgrade. Composer replaces those files, so the modification disappears without warning and whatever depended on it breaks.

Finding them means comparing the installed code against a clean copy of the same Magento version. Each difference then has to be moved somewhere it will survive: a plugin, an observer or a patch applied through Composer. Existing Composer patches need checking too. Some will no longer apply, and some will have been fixed upstream.

The Upgrade Compatibility Tool

For Adobe Commerce, Adobe provides the Upgrade Compatibility Tool. It is a command line tool that analyses a customised installation against a target version and reports problems to fix before you upgrade. Treat it as a first pass that shortens the audit, not a replacement for testing.

On Magento Open Source, static analysis with the Magento coding standard and a PHP compatibility check cover similar ground.

Do the upgrade on a branch, in staging

Never upgrade production in place. Create a branch in Git, update the Magento version and extension versions in Composer, and resolve the dependency conflicts there. Then run bin/magento setup:upgrade, setup:di:compile and setup:static-content:deploy, and fix what fails.

The staging environment should run the target versions of PHP, the database, the search engine and the cache services. Commit composer.lock so that production installs exactly the package versions you tested.

Back up, then rehearse with real data

Take a recent copy of the production database, with customer data anonymised where your data policies require it, and run the full upgrade against it.

Time the rehearsal. How long setup:upgrade and a full reindex take on real data tells you how long the maintenance window needs to be. Rehearse the restore as well. A backup that has never been restored is a hope, not a rollback plan.

Make sure staging cannot email real customers, and that payment methods and integrations point at sandbox accounts.

Regression testing: what to check

Work from a written test script so the checks can be repeated after every fix. At a minimum, cover:

Checkout: guest and logged-in orders, for each product type you sell.
Payments: every method, including card authentication, and capture and refund from the admin.
Shipping: rates and methods for each destination, and any carrier or label integration.
Tax: VAT for domestic and cross-border orders, and how prices display.
Promotions: cart price rules, catalogue price rules, coupon codes and free shipping thresholds.
Customer accounts: registration, login, password reset, addresses and order history.
Search and navigation: search results, layered navigation and sorting.
Indexers: all valid, and a full reindex completes.
Cron: scheduled jobs run and finish without errors.
Emails: order, invoice, shipment and account emails send with the right templates.
Integrations: ERP, PIM, stock and order feeds, marketplaces and analytics tracking.
Admin: saving products, creating orders and imports.

Compare performance before and after

Record a baseline on the current version before you start: server response time on the main page types, with and without the full-page cache, plus reindex times and your Core Web Vitals. Take the same measurements on staging after the upgrade.

An upgrade can move performance in either direction. If the numbers get worse, treat it as a defect to fix before go-live, like a failed checkout test. Our performance optimisation page describes what we measure.

Go-live: maintenance window and rollback

Choose the window from your own analytics: the quietest hours of a quiet day, well clear of a campaign or a peak period. Agree a freeze on other changes, and tell customer service and the warehouse what is happening.

Write the deployment as a step-by-step runbook with a named owner for each step. Include maintenance mode, a final backup of the database, code and media, the deployment, a smoke test that ends in a real order, and a fixed time for the go or no-go decision.

The rollback plan matters most. Restoring the database discards any orders placed after the backup, so the decision to roll back has to be made before the store reopens. Agree in advance which failures trigger it. After go-live, watch error logs, payment success, order volume, cron and indexers for the first few days.

The checklist

Confirm your current version and its end of support date.
Apply any outstanding security patches to the current version.
Read the release notes for the target version and every version in between.
Check Adobe’s system requirements for the target version and confirm them with your host.
List every extension. Remove unused ones and find compatible versions of the rest.
Audit custom modules, theme overrides and Composer patches.
Find and relocate any core modifications.
Run the Upgrade Compatibility Tool or static analysis and fix what it reports.
Record a performance baseline on the current version.
Upgrade on a Git branch and deploy it to a staging environment that matches the target infrastructure.
Rehearse with a recent copy of the production database and time each step.
Run the full regression test script and fix the failures.
Compare performance against the baseline.
Write the go-live runbook and rollback plan, test the restore and agree the maintenance window.
Back up, deploy, smoke test with a real order, then reopen.
Monitor closely for the first few days.

What to do next

Start with two facts: which version you are on, from bin/magento --version, and when Adobe stops supporting it. Then produce the extension list. Together they tell you how large the job is and how soon it needs to start.

If the audit turns up core modifications or abandoned extensions, deal with those first as separate work. Our migrations and upgrades page explains how we run this process, and a support and maintenance retainer is how a store stays close enough to the current release that an upgrade remains a routine job.

Magento 2 upgrade checklist: how to plan a 2.4.x upgrade