Mage-OS 3: What's In It, and What It Breaks

Mage-OS 3.0 landed on May 18, 2026, built on the Magento Open Source 2.4.9 base. Four releases have followed since: 3.1 for stability, then 3.2, 3.3 and 3.4 carrying Adobe's July and August security content. If you're here because of that last one, 3.4.0 is the August account-takeover bulletin and you should be deploying it rather than reading release notes.

Before any of the detail, one distinction makes the release notes far easier to read. Some of what you'll see attributed to Mage-OS 3 is Mage-OS's own work, and some of it arrives with the 2.4.9 base and would land on you just the same if you stayed on Magento. Those two categories have very different implications for your upgrade plan, and most write-ups blend them.

The installer

bin/magento install is now a guided wizard covering database, admin account, store configuration, services, sample data and theme selection.

Two details make it more than a nicety. It auto-detects MySQL/MariaDB, Redis, OpenSearch/Elasticsearch and RabbitMQ on standard ports, so the usual first-run failure — a typo in a host or port you'll spend twenty minutes finding — mostly stops happening. And it saves config as it goes, so a failed run resumes where it stopped instead of starting over, with passwords re-prompted.

It also asks about Hyvä during setup and wires up the Composer packages and theme if you say yes. Hyvä is still commercially licensed; the installer saves you the setup, not the fee.

The old setup:install is unchanged, so scripted provisioning and CI keep working exactly as they do now.

The Minimal Distribution

The opt-in mage-os/product-minimal-edition package installs around 98 core packages. Page Builder, Inventory, GraphQL and similar components become individual Composer packages you add when you want them, and Mage-OS has put up a package browser for finding them.

The case for it is attack surface and clarity about what you're actually running. Code you never enabled still sits on disk, still loads in the autoloader, and is still yours to patch — the same reason we tell clients to remove unused extensions instead of disabling them.

Two caveats. The full distribution remains the default, so nothing changes unless you choose it. And this is a decision for new builds: retrofitting an existing store onto the minimal edition means proving that nothing in your theme, integrations or extension set depends on a module you just took away. That's an audit, not a Composer command.

Returns and the admin activity log

Two merchant-facing modules ship in the box. mage-os/module-rma gives customers a returns request in their account and merchants a review-and-approve workflow. mage-os/module-admin-activity-log records who changed what and when.

Both need enabling in configuration after you upgrade. The activity log is based on the open-source KiwiCommerce extension, modernized by Mage-OS instead of written from scratch.

These are the two most interesting things in the release, because Adobe's own documentation marks both capabilities as available only in Adobe Commerce. We've written up what that does to the comparison separately.

Four tools you were installing anyway

Bundled by default: the n98-magerun2 CLI (vendor/bin/n98-magerun2), Ignition error pages with stack traces and editor jump links, Varnish Extended, and configurable admin branding. All four are existing third-party open-source packages that Mage-OS pins into the metapackage — Swissup's, Elgentos', element119's and n98's respectively — so what you're getting is the selection and the integration.

Two notes for the upgrade itself. Ignition disables itself in production, which is the correct default and worth confirming on your first deploy anyway. Varnish Extended means regenerating your VCL after upgrading, so put that on the runbook.

Two things people expect to find in 3.0 and don't. The theme optimization module — back/forward cache, speculative preloading, view transitions — and the PCI DSS 4.0 admin policies both arrived earlier, in Mage-OS 2.0 back in October 2025, so an existing 2.x store already has them. And the M137 admin theme has never been bundled at all; it's a Mage-OS Lab package you install yourself. We've covered what all of those actually do separately.

What breaks

PHP 8.2 is out. The minimum is 8.3, 8.4 is recommended, 8.5 works, and Composer flatly refuses to install on anything older — so this is a hosting task before it's an upgrade task. It isn't a Mage-OS decision either; Magento Open Source 2.4.9 draws the same line.

Symfony moved to 7.4 LTS, so extensions extending Symfony 6.x classes need updating and CLI commands are where you'll notice first. I checked Adobe's 2.4.9 release notes on this one, because it gets misreported constantly: the Symfony update is upstream. It's coming for you on Magento too, and it isn't a reason to avoid Mage-OS.

Adobe's analytics modules are gone, and that one is Mage-OS's own doing — module-analytics plus the catalog, customer, quote, review, sales and wishlist analytics modules, and the Marketplace module with them. Unless something you run depends on Adobe's data collection, and for most stores nothing does, you won't notice.

setup:backup is gone along with the Magento_Backup module. Use filesystem and database tooling suited to your environment, which is what anyone with a real backup process was doing anyway. Mage-OS's release notes list this among the removals, and I couldn't confirm from Adobe's 2.4.9 notes whether the removal is upstream or theirs — so treat the attribution as open. The effect on you is identical either way.

ext-ftp is no longer required, which removes a dependency and breaks nothing.

Lazy object loading is on — Mage-OS's own DI work, with escape hatches: set lazy_object_loading_disabled to true in app/etc/env.php, or mark a single class with the #[Magento\Framework\ObjectManager\Attribute\NonLazy] attribute. Useful to know before you spend a day debugging an extension that assumes eager construction.

The support policy deserves a line of its own

Mage-OS supports only its latest release for security patches and community support.

Set that against Adobe, where each release line gets a three-year standard support window. It isn't a flaw — it's the maintenance commitment a volunteer-funded association can actually keep — but it does change what running Mage-OS asks of you. Parking on a version for two years and taking patches is not the arrangement. You upgrade on their cadence, which is roughly two feature releases a year in April and October, plus security releases within days of Adobe's second-Tuesday patches.

For a store with a working deployment pipeline, that's routine. For one that upgrades reluctantly, it's a reason to fix the pipeline before switching distributions.

Taking it

Upgrading from an earlier Mage-OS:

composer require mage-os/product-community-edition=^3.0 --no-update
composer update
bin/magento setup:upgrade

A new install:

composer create-project --repository-url=https://repo.mage-os.org/ \
  mage-os/project-community-edition=3.0.0 <install-directory>
cd <install-directory>
bin/magento install

Check the current version before you run either — 3.4.0 is the latest as of mid-August 2026, and pinning 3.0.0 on a new build would install a version missing two months of security patches.

The order that keeps this boring: confirm PHP 8.3 or newer on your hosting, take a staging copy, run the upgrade there, put every paid extension through a real test, regenerate the Varnish VCL, then deploy with the previous release ready to restore. On a store I know well I'd expect that to be a couple of days, most of it spent on the extension testing rather than the upgrade. If you're coming from Magento rather than an earlier Mage-OS, the distribution switch is a separate exercise and doing both at once means you won't know which change caused a regression.

Emyrix runs Magento, Adobe Commerce and Mage-OS upgrades, including the extension testing that decides how long one takes. We have no commercial relationship with the Mage-OS Association. If you want yours scoped, get in touch.

Release contents, dates, package names and the support policy are from mage-os.org; the Symfony 7.4 attribution was checked against Adobe's Magento Open Source 2.4.9 release notes. Versions move quickly, so confirm the current release before planning against a specific one.