Magento upgrades have a reputation for breaking things, usually because they’re rushed onto production. Upgrades themselves are routine when you follow a process. This is the checklist we use.
1. Read before you touch anything
- Release notes for the target version, including security fixes and known issues.
- System requirements: supported PHP, MySQL or MariaDB, OpenSearch, Composer, Redis and Varnish versions. An upgrade often means updating the server stack too.
- Support dates: plan to stay on a release line that’s still receiving security patches.
2. Take stock of extensions and customizations
List every third-party extension and custom module, with its version. For each one, check that the vendor supports your target Magento and PHP versions. Extensions with no compatible release are the most common reason upgrades stall, so find them first.
Look for core overrides and custom code that relies on deprecated APIs. A quick search of app/code and your theme for overridden templates and plugins will show where testing needs to focus.
3. Build a staging copy of production
Upgrade a copy, never the live store. Staging should match production as closely as possible: the same code, a recent database copy (with customer data handled appropriately), media and the same server versions you’ll run after the upgrade.
Take a full backup of production code, database and media before you start, and confirm you can restore it.
4. Run the upgrade on staging
With the Composer root update plugin installed, a typical Magento Open Source upgrade looks like this. Use magento/product-enterprise-edition for Adobe Commerce, and replace <target-version> with the release you’re moving to.
bin/magento maintenance:enable
composer require-commerce magento/product-community-edition <target-version> --no-update
composer update
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento indexer:reindex
bin/magento cache:flush
bin/magento maintenance:disableExpect to update extensions and fix compatibility issues along the way. Commit the resulting composer.json and composer.lock. They’re what you’ll deploy to production.
5. Test what makes money
Automated tests help, but walk through the store as a customer and as staff:
- Browse categories, layered navigation and search.
- Add to cart, apply coupons, and complete checkout with every payment method you offer.
- Check shipping rates, taxes and order confirmation emails.
- Create, invoice, ship and refund an order in the admin.
- Confirm cron jobs run and indexers are up to date.
- Check integrations: ERP, accounting, shipping labels, marketing feeds.
- Compare page speed against production.
Review var/log/system.log and var/log/exception.log after testing for errors that didn’t surface on screen.
6. Plan the go-live
- Schedule a maintenance window at your quietest time.
- Take a fresh backup immediately before deploying.
- Deploy the exact code tested on staging, using the committed
composer.lock. - Write down the rollback steps and who decides to use them.
7. Watch it after launch
For the first few days, monitor error logs, cron, order volume and payment failures. Check Google Search Console for crawl errors if URLs or templates changed.
Keep it from becoming a big project
Upgrades are painful when they’re years apart. Applying security patches as they’re released and moving between minor versions regularly keeps each step small. That’s the point of a maintenance plan.
If you’re facing an upgrade, or inherited a store that hasn’t been updated in a while, we can help.