Insights
Upgrading to Mage-OS 4.0 from 3.6: what changes and what to check
Mage-OS 4.0.0 was released on 30 October 2026. It is built on the same Magento Open Source 2.4.9 base as 3.6.0, with no change to PHP support, so it is a drop-in upgrade from 3.6.x rather than a platform move, and the release notes state that there are no infrastructure changes associated with it. The reason to plan it rather than defer it is that 3.6.0 reached end of life with the same release. Three things are worth checking before you run the commands: a Composer conflict around the new SEO module, a major version bump in magerun, and two inventory paths that change even if you leave the new reservations feature switched off.
Tested on a staging copy, then applied in an agreed window, with a rollback plan.
Why 3.6 is already end of life
Mage-OS 3.6.0 was itself a security release, published on 14 October 2026 to port Adobe's October isolated patch (APSB26-153), which covered vulnerabilities including one rated CVSS 10.0. Every 3.x store was told to upgrade to it. Sixteen days later, Mage-OS's release policy retired it alongside the 4.0.0 launch.
That is an awkward sequence if you patched in October and assumed you were settled for a while. It is not a reason to rush the upgrade in production on a Friday afternoon, but it does mean a 3.6.0 store is now running a version that will not receive the next security port. For how security releases reach a Magento or Mage-OS store in general, see our Magento upgrades and security patching page.
The headline additions in 4.0 are an admin AI assistant called Mago, AI discoverability for the storefront, native product feeds for the major advertising channels, passwordless login with passkeys, new admin tooling and a substantial overhaul of Multi-Source Inventory. If you are still deciding whether Mage-OS is the right distribution at all, start with what Mage-OS is, and for the server side see our Mage-OS hosting requirements guide.
Before you upgrade
The module-seo Composer conflict
Mage-OS 4.0 bundles a new mage-os/module-seo, which supersedes mage-os/module-meta-robots-tag and mage-os/module-hreflang and declares a Composer conflict with both.
Whether that bites you depends on your own composer.json. Upgrading the metapackage on its own resolves cleanly, because the old modules leave the dependency set at the same moment the new one arrives. If your project requires either module directly, Composer will refuse the upgrade. Remove them first:
composer remove mage-os/module-meta-robots-tag mage-os/module-hreflang --no-updateYour settings are not lost. The new module ships data patches and a bin/magento import command that bring across existing meta-robots-tag and hreflang configuration, and it reports the result as an admin message.
magerun moves to version 10
n98/magerun2-dist moves from ^9.4 to ^10.0. That is a major version bump, so any deployment script, cron job or CI step that calls magerun should be checked against the new version before you rely on it.
Customised order placement or shipment logic
Source-level reservations are off by default, but two inventory paths change regardless. The place-order lock is now taken at source level at order submission, which also covers the admin path, and shipments resolve the allocated source instead of falling back to the default source.
If your store has customised order placement or shipment source selection, those are the paths to test. A single-source store with stock, shipping and order placement left as Magento ships them has far less to check here than a multi-source store with bespoke allocation logic.
The upgrade commands
From an existing Mage-OS version:
composer require mage-os/product-community-edition=^4.0 --no-update
composer update
bin/magento setup:upgradeExpect the dependency tree to grow. A default install goes from 541 to 571 packages. The AI configuration layer brings the Symfony AI platform components along with symfony/http-client, symfony/serializer, symfony/property-info and symfony/uid, and passkey authentication brings web-auth/webauthn-lib, web-auth/cose-lib and spomky-labs/cbor-php.
After the upgrade
Recompile. The compiled dependency injection format has changed, so run your compile step again. Extensions that read compiled configuration directly may need attention, which is a good reason to do this on staging with your full extension set installed rather than on a clean install.
Make sure consumers are running. The mageosSeoFeedRegenerate consumer is what builds the SEO and AI discoverability output, so queue consumers need to run under cron or a supervisor. If cron is unreliable on your server, the symptoms are easy to mistake for a content problem: see Magento cron not running.
Fill in the Organisation details. module-seo starts outputting structured data as soon as it is installed, and that output stays incomplete until Marketing > SEO > Organization is filled in. The same record feeds /llms.txt. We cover that side in Mage-OS 4.0's built-in SEO and llms.txt.
Check your indexers. The MSI work adds parallel full reindexing per stock dimension and changes how reservations are cleaned up, so confirm indexer state after the upgrade rather than assuming it. Our reindex and indexer guide covers the usual repairs.
What is switched off by default, and what is on
Most of 4.0's new features are off until you turn them on. Off by default: passkey login, the AI discoverability documents and AI-crawler rules, Stock Visualizer, source-level reservations, and Mago. Shopping feeds produce nothing until a feed is defined.
On by default, in the admin only: ScopeHint popovers and config paths, and the Extension Directory page with its dashboard tip panel.
Two of these send data outside the store, which is worth knowing before anyone switches them on. Mago sends prompts to whichever AI provider you configure. The Extension Directory, in its default Direct mode, has admin browsers fetch the public catalogue feed; Proxy mode avoids that.
Staging checklist
- Check whether your root
composer.jsonrequiresmodule-meta-robots-tagormodule-hreflang, and remove them first if it does - Confirm the meta-robots-tag and hreflang import reported success as an admin message
- Run the upgrade on a staging copy with your full extension set, not a clean install
- Recompile, and test any extension that reads compiled configuration directly
- Test customised order placement end to end, including the admin path
- Test shipment source selection, which now resolves the allocated source
- Check every script, cron job and CI step that calls magerun against version 10
- Confirm queue consumers run under cron or a supervisor,
mageosSeoFeedRegenerateincluded - Fill in Marketing > SEO > Organization before judging the structured data output
- Review the structured data the SEO module now emits, since it is live as soon as it is installed
- Decide deliberately on Mago and the Extension Directory's Direct mode, both of which send data off the store
- Confirm indexer state after the upgrade
How a managed host helps
Most of the work above is application work, and it belongs with whoever develops your store. The hosting side is narrower: queue consumers and cron need to keep running under a supervisor rather than silently stopping, a staging environment needs to match production closely enough that an extension problem shows up there first, and the upgrade needs a window with a way back if something unexpected surfaces.
EveryHost can host Mage-OS stores on our managed plans, and the stack sits alongside the usual Magento components, with Redis or Valkey set to match your Magento version. See managed Mage-OS hosting for what that covers, and Magento upgrades and security patching for how we handle patch windows. If you are on Magento Open Source 2.4.9 rather than Mage-OS, the underlying requirements are the same: see Magento 2.4.9 hosting requirements.
Sources
All accessed 3 November 2026.
- Mage-OS 4.0.0 Feature Release, 30 October 2026
- Mage-OS October Update: Security, AI and What's Next, 1 November 2026
Frequently asked questions
Planning a Mage-OS 4.0 upgrade?
We can host Mage-OS on our managed plans, keep queue consumers and cron running under supervision, and give you a staging environment that matches production closely enough to catch extension problems before your customers do.