Language: English
Request a service

How to Upgrade Magento 2: A Safe Step-by-Step Upgrade Guide

Upgrading Magento 2 does not have to be scary. This step-by-step guide covers planning, compatibility checks, Composer commands, testing and rollback, so your store stays secure and stable.

Hasan Gültekin4 min read

Keeping Magento 2 up to date is essential. Every release brings security fixes, and older versions eventually stop receiving patches. Yet many stores postpone upgrades because the last one went badly.

Most failed upgrades are caused by poor preparation, not by Magento itself. This guide shows a safe, repeatable process.

Why upgrade?

  • Security: older versions stop receiving security patches. An unpatched store is a target for card skimmers and attacks.
  • Compatibility: new PHP, MySQL/MariaDB, OpenSearch and other service versions require newer Magento versions.
  • Performance and bug fixes
  • Extension support: vendors drop support for old versions over time.

Types of upgrades

Type Example Risk
Security patch Applying an isolated security patch Low
Patch release 2.4.x-p1 to 2.4.x-p2 Low to medium
Minor/feature release 2.4.x to 2.4.y Medium to high
Infrastructure change New PHP or database version together with Magento High

Check Adobe’s release notes and lifecycle policy to know which versions are supported and until when.

Step 1: Check system requirements

Each Magento release supports specific versions of:

  • PHP
  • MySQL or MariaDB
  • OpenSearch (or Elasticsearch for older versions)
  • Redis, Varnish, RabbitMQ
  • Composer

Compare the requirements of your target version with your server. Upgrading the infrastructure is often part of the project.

Step 2: Audit extensions and customisations

This is where most problems come from.

  1. List all modules:
bin/magento module:status
composer show | grep -v magento/
  1. For each third-party extension, check whether the vendor supports your target version
  2. Review custom modules for deprecated code, removed classes and changed interfaces
  3. Check theme overrides: templates copied from core may need updating
  4. Remove extensions you do not use

Step 3: Prepare a staging environment

Never upgrade production first. Your staging should match production:

  • Same PHP and service versions as the target setup
  • A recent copy of the production database (anonymised)
  • Same configuration and extensions

Step 4: Back up everything

  • Database dump
  • Code (your Git repository)
  • app/etc/env.php and app/etc/config.php
  • Media files

And make sure you know how to restore them. A rollback plan is part of the upgrade.

Step 5: Run the upgrade on staging

Enable maintenance mode:

bin/magento maintenance:enable

Update the Magento version requirement with Composer (Magento Open Source example):

composer require-commerce magento/product-community-edition 2.4.x-pX --no-update
composer update

The require-commerce command comes from Magento’s Composer root update plugin, which also updates other root dependencies. Alternatively, update composer.json manually and run composer update.

Then:

rm -rf generated/code/* var/cache/* var/page_cache/* var/view_preprocessed/*
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:disable

Replace 2.4.x-pX with your target version. For more commands, see my Magento 2 commands cheat sheet.

Step 6: Fix errors

Common issues:

  • Composer conflicts: an extension requires an older version of a dependency. Update or replace the extension.
  • Compilation errors: custom code uses removed classes or changed method signatures.
  • Database schema errors: a module’s declarative schema conflicts with the new version.
  • Frontend issues: outdated template overrides in your theme.

Step 7: Test thoroughly

At minimum:

  • Home, category, product, search pages
  • Add to cart, cart, checkout with each payment and shipping method
  • Customer registration, login, account pages
  • Admin: orders, invoices, credit memos, product saves, imports
  • Emails (order confirmation, password reset)
  • Integrations: ERP, PIM, feeds, analytics, tracking
  • Cron jobs and indexers
  • Performance compared with before

Automated tests help a lot for repeated upgrades.

Step 8: Deploy to production

  • Choose a quiet moment (not before a sale or holiday)
  • Use your normal deployment pipeline, not manual changes on the server
  • Monitor logs (var/log/exception.log, var/log/system.log), errors and conversion rate after release

Rollback plan

If something goes seriously wrong:

  1. Enable maintenance mode
  2. Restore the previous code release
  3. Restore the database backup (note: orders placed after the backup will need attention)
  4. Flush caches and disable maintenance

Orders placed between the upgrade and a rollback are the main risk, so keep the window short and test well beforehand.

How often should you upgrade?

Plan to apply security patches soon after release, and do larger version upgrades at least once a year. Small, regular upgrades are much easier than a big jump every few years.

Frequently asked questions

How long does a Magento upgrade take?

A patch upgrade on a clean store can take hours. A version upgrade with many extensions and infrastructure changes can take weeks including testing.

Can I skip versions?

Yes, you can upgrade directly to the target version, but review the release notes of every version in between for breaking changes.

Do I need to upgrade to Hyvä at the same time?

No. Keep upgrades and frontend projects separate where possible, to reduce risk. When you are ready, see my Luma to Hyvä migration guide.

Need a safe Magento upgrade?

I plan and carry out Magento 2 and Adobe Commerce upgrades, including extension audits, infrastructure updates and testing. See my Magento 2 and Hyvä service or request an upgrade plan.