Upgrading your Magento store

You can upgrade your store to a newer Magento version yourself, from the portal. This page explains what the upgrade does, how to start one, and what protects you if something goes wrong.

What a Magento upgrade actually changes

A Magento upgrade replaces three things in your store:

1. Application code — the PHP files that make Magento work
2. Database schema — the structure of the tables that hold your data (products, orders, customers, etc.)
3. Compiled / cached artifacts — generated code, static assets, page caches

Your data (products, orders, customers, settings) is preserved across upgrades. The schema is migrated to the new shape; the data inside is moved to fit.

Starting an upgrade

Open your store's Maintenance tab and use Update Magento. It shows the next update your store can take — always the smallest step available for your store — and one of two kinds:

• A security update (for example 2.4.8-p2 → 2.4.8-p3) — routine, and the one to take as soon as it's offered. You click Schedule update.
• A new Magento release that runs on the same setup your store uses today, so it installs the same way. It's a bigger application change — custom extensions and theme work may need updating — so the portal asks you to tick an acknowledgement and click Schedule release update.

If your store has fallen behind, the portal tells you how many more steps follow this one; you can schedule the next as soon as this one finishes. When your store is already on the latest security update for its release, the section simply says so. Some larger version jumps can't be done in place and aren't offered here — to move onto a newer setup (newer PHP and database), see Moving your store to the newest setup; for anything else, contact support to plan it with us.

Upgrades run only during your store's maintenance window, never immediately — so you schedule the update and it starts in your next window. There's no "update now": to have it happen sooner, move your window. You can cancel a scheduled upgrade any time before it starts. Your maintenance window is on the Settings tab if you want to change when it falls — see Your maintenance window.

Before you upgrade

• Your Adobe Commerce Marketplace keys must be set. Upgrades download the official Magento packages using your own Marketplace keys, so an upgrade won't start until you've added them — see Your Adobe Commerce (Marketplace) keys.
• You don't need to back up first — the upgrade does it for you. A full backup is taken automatically immediately before the upgrade runs, and if that backup can't be completed the upgrade is called off and your store is left untouched (see below). That backup is your rollback point.
• Consider trying it on a sandbox first. If your store has custom extensions or theme work, create a sandbox — a full copy of your store — update the copy, and check your storefront and checkout before updating your live store. It's optional: a straightforward store can update directly.

What happens during an upgrade

The upgrade runs in this rough order. Knowing the steps helps when you read the status updates:

1. Forced pre-upgrade backup — your store briefly enters maintenance and a fresh full backup is taken first. If the backup can't be completed, the upgrade stops here and your store is brought back online unchanged — so "we backed up first" is always true.
2. Maintenance mode — your store shows a maintenance page to visitors; the admin is offline too while the upgrade runs.
3. Code update — the new Magento application files are pulled in.
4. Schema migration (setup:upgrade) — the database tables are updated to the new version's shape. This is the irreversible step; once schema migration completes, the only way back to the previous version is restoring the pre-upgrade backup.
5. Code compilation (setup:di:compile) — Magento generates optimized class files. This is CPU-heavy and is most of the duration.
6. Static asset deployment (setup:static-content:deploy) — CSS, JavaScript, and theme assets are recompiled.
7. Cache flush and web restart — caches are cleared and the web tier is restarted so the new code takes effect.
8. Health check — while the store is still in maintenance, we check it runs the new version, its database is up to date and it serves pages correctly.
9. Maintenance mode off — only once that check passes is your store live again on the new version.

If a step fails, your store stays in maintenance mode. By then the update may already have changed part of your store, so we don't put a half-updated store in front of your visitors. Update Magento tells you what happened; to go back, restore the pre-upgrade backup from your Backups tab. (If the update couldn't start at all — for example the backup failed — nothing was changed and your store is brought back online.)

You can leave the page and come back; the upgrade keeps running on its own, and Update Magento shows it as updating… until it finishes. Once it's done, the section shows the version and date it updated to — or, if it failed, the reason.

How long it takes

Your store shows a maintenance page for usually 10–30 minutes — a security update is towards the shorter end, a new release towards the longer. The duration grows mostly with:

• Number of themes (each gets its CSS recompiled)
• Number of locales (each gets its own static asset deploy)
• Catalog size (affects the index rebuild step)
• Custom extension count (affects the dependency injection compilation step)
• Existing custom code (more compiled artifacts to regenerate)

When to upgrade

• Security patches: as soon as possible after they're offered. These often address vulnerabilities being actively exploited.
• New releases: after a brief observation period (1-2 weeks after release) to let any post-release bugs surface in the wider Magento community.
• In your maintenance window: every upgrade runs in your store's lowest-traffic window by design, to minimize the visible maintenance page.

After it completes

Once your store is back online on the new version, run your standard checks: place a test order, log in to the admin, open a representative product page, and confirm emails still go out. Keep an eye on your error logs and support inbox for the next day or two.

Rolling back an upgrade

If the upgrade caused a regression you can't tolerate, restore the pre-upgrade backup — the one the upgrade took automatically, right before it ran — from your Backups tab. Your store returns to exactly the state it was in immediately before the upgrade. See Backing up and restoring your store.

Because that backup is taken moments before the upgrade, it's the tightest possible rollback point. You will still lose anything that changed after it was taken — any orders, customer registrations, or content edits made during or after the upgrade attempt — because those events aren't in the backup. The rollback window is bounded by your retention; see the backups page.

What can go wrong, and what you can do

Symptom after upgrade	What it usually means	What to do
Store shows a 503 / "service unavailable" page that doesn't go away	Maintenance mode wasn't disabled, or static content didn't deploy	Wait 5 more minutes (long-running deploy); if it persists, restore the pre-upgrade backup
Admin panel shows "Please upgrade your database"	setup:upgrade did not complete; schema is in an inconsistent state	Restore the pre-upgrade backup — do not attempt to use the store; data integrity is at risk
Admin loads but storefront pages 500	Likely a compilation issue or a cache that didn't flush	Try clearing your browser cache first; if it persists, run Compile code, then Flush cache (Maintenance tab → Refresh / rebuild the store)
A specific extension stops working	Extension isn't yet compatible with the new Magento version	Disable it from the Extensions tab, or contact the extension vendor for an update
Storefront pages render unstyled	Static content wasn't deployed, or deployed for the wrong store/theme	Run Deploy static content (Maintenance tab → Refresh / rebuild the store)

Magento version requirements (for context)

Each Magento version needs specific underlying software (PHP, database, search). You don't manage any of this — the right stack is set up and kept in step with your version for you. For the full list of supported versions and exactly what's bundled with each, see Supported Magento versions.