Announcing Mage-OS 3

Mage-OS Distribution 3.0 is built on Magento Open Source 2.4.9. Headline changes: a brand-new interactive installer, Return Merchandise Authorization (RMA) and Admin Activity Log, better developer features, and an opt-in Minimal Distribution.

Our foundation

Magento Open Source 2.4.9 brings broad upstream improvements across GraphQL, B2B, infrastructure, and accessibility. Mage-OS 3 layers release engineering, security work, and the features below on top. See the Magento Open Source 2.4.9 release notes for upstream details.

Recommended software:

What’s new in Mage-OS 3

Interactive installer: bin/magento install

All new, for easy setup of new Mage-OS installations:

bin/magento install

A guided wizard walks you through database, admin account, store config, services, sample data, and theme selection. Along the way it:

• Auto-detects services — MySQL/MariaDB, Redis, OpenSearch/Elasticsearch, and RabbitMQ on common ports.
• Resumes on failure — config is saved; the next run picks up where you left off (passwords are re-prompted).
• Protects production — explicit confirmations before destructive operations; warns if it suspects production.
• Installs Hyvä Theme out of the box — pick Hyvä during the theme step and the installer adds the Composer packages and applies the theme for you, no extra setup required.
• Handles post-install setup — applies the chosen theme, sets indexers to schedule mode, manages two-factor authentication (2FA), and flushes caches.

The original setup:install is unchanged, so automation isn’t affected. Contributed by @DavidLambauer, with 410 unit tests (#191).

PHP 8.5 ready, 8.4 improved

Mage-OS 3.0 supports PHP 8.5 alongside 8.3 and 8.4. We built in PHP 8.4 lazy object loading for faster response times when the system is compiled.

RMAs

Mage-OS now includes built-in RMA support via mage-os/module-rma. Enable it in configuration after upgrading. Customers request returns from their account; merchants can review and approve requests, and communicate with the customer. See the RMA readme for more details.

Admin Activity Log

mage-os/module-admin-activity-log brings admin action logging — a built-in audit trail of who changed what, when, for auditing and compliance. This is based on the open source KiwiCommerce Admin Activity extension, with heavy refactoring for modernization and security. See the Admin Activity Log readme for more details.

“Update available” indicator in the admin footer

The admin footer now shows an “Update available: X.Y.Z” link when a new release is available. The version check happens in the background, by directly checking your composer repositories. This can be disabled in configuration.

Minimal Distribution

Mage-OS 3.0 introduces mage-os/product-minimal-edition — a lean install with only ~98 core packages installed by default. Modules, themes, and language packs are available as individual Composer packages, so you only install what you use. Best for teams comfortable composing their own stack and looking to optimize every millsecond.

Packages that aren’t included by default should be auto-installed by composer for extensions that need them, as long as those dependencies are declared properly. It’s up to you to add what you need (Page Builder, Inventory, GraphQL, etc).

For more details, and to browse all of the packages that are available and included, see our website’s new Package Browser.

Developer toolkit, bundled by default

Mage-OS 3.0 bundles four well established community tools, to make your experience better:

n98-magerun2

The de-facto Magento command-line interface (CLI), now shipped by default. sys:info, cache:flush, db:console, dev:console, and dozens of inspection commands. See the official Magerun2 readme for more details. See the available commands with:

vendor/bin/n98-magerun2 list

Maintained by netz98 GmbH — Christian Münch (@cmuench), Tom Klingenberg (@kissifrot) and the n98-magerun2 contributors.

Ignition for Magento

Swissup Labs integration for spatie/ignition, a more helpful error page. Developer mode exceptions will now give you a stack trace, request context, environment details, and editor-jump links. It will also give helpful instructions for how to fix some setup and DI issues. Auto disabled in production, so it can’t leak internals. See the Ignition module readme for more details.

Maintained by Swissup Labs.

Varnish Extended

Optimizations, richer cache controls, and operational tooling for using Varnish in production. Regenerate and update your Varnish VCL to apply the improvements after upgrading. See the VarnishExtended readme for more details.

Maintained by Elgentos — Peter Jaap Blaakmeer and the Elgentos team.

Custom Admin Logo

Replace the admin panel and login-screen logo without touching a theme — a small but meaningful branding touch. Set your own logo at Admin > Stores > Configuration > Advanced > Admin > Admin Logo.

Maintained by element119 — Kiel Pykett (@kpykett).

Add-on module updates

• Page Builder Widget 1.4.1 → 1.5.0 — PHP 8.5 compatibility and input sanitization hardening (#20, @SamueleMartini); previewTemplates XML node merge fix (#21, @dadolun95)
• Page Builder Template Import/Export 1.8.0 → 1.8.1 — int return type on Console Command execute() (#20, @rhoerr)

All other independently-versioned add-ons (Automatic Translation, Inventory Reservations Grid, Meta Robots Tag, Theme Optimization, M137 admin theme) are unchanged since 2.3.0.

Compatibility & upgrade notes

• PHP 8.3 minimum. Composer will refuse to install Mage-OS 3.0 on PHP 8.2 or earlier. PHP 8.4 is recommended; 8.5 is supported.
• Symfony 6 → 7. Extensions extending classes in symfony/console, symfony/intl, symfony/mailer, symfony/mime, symfony/process, or symfony/string need updates.
• Adobe analytics removal. Remove any references to module-analytics, module-catalog-analytics, module-customer-analytics, module-marketplace, module-quote-analytics, module-review-analytics, module-sales-analytics, and module-wishlist-analytics before upgrading.
• ext-ftp dropped. No longer required out of box; hosting providers and container images can stop installing it.
• Magento_Backup module removed. The legacy bin/magento setup:backup command is gone — use filesystem and database backup tooling appropriate for your environment.
• If you encounter problems with lazy object loading, you can disable it in app/etc/env.php by setting lazy_object_loading_disabled to true. You can also add the #[Magento\Framework\ObjectManager\Attribute\NonLazy] attribute to a class to exclude it from lazy loading.

Mirror updates

The latest Magento versions, including 2.4.9, are also available from our public mirror at mirror.mage-os.org — a drop-in replacement for repo.magento.com (except Magento Marketplace), installable without Adobe Marketplace credentials.

Thanks to everyone who contributed!

• @DavidLambauer (David Lambauer) — Interactive installer (#191)
• @rhoerr (Ryan Hoerr) — Release engineering, admin activity log, PHP 8.4 DI lazy-object loading (#225 / #226), admin footer update indicator (#207), analytics module removal
• @SamueleMartini (Samuele Martini) — RMA module, PHP 8.5 compatibility
• @dadolun95 (Davide Lunardon) — Mage-OS module development, maintenance, and support
• @marcelmtz (Marcel Martinez) — Release engineering and maintainership

And thanks to the maintainers of the community projects we now ship by default: netz98 (magerun2), Swissup Labs (Ignition), Elgentos (Varnish Extended), element119 (Custom Admin Logo) — and to the PHP library authors pulled in alongside the upstream framework bumps: Stomp-PHP, Till Krüss (predis), Spomky-Labs (aes-key-wrap), the Laravel team (prompts), Nicolas Grekas and the Symfony Community (symfony/cache), and the PHP-DB project (phpdb).

Installation

New installations

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

The wizard detects local services, walks you through configuration, and handles post-install setup. bin/magento setup:install still works if you prefer the classic flow.

For the lean install, see the Minimal Distribution page.

Upgrading Mage-OS

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

Migrating from Adobe Commerce or Magento Open Source

See our migration guide for detailed instructions.

We hope you enjoy Mage-OS 3.0. As always, please report issues on GitHub and join the conversation on Discord.

Want to participate?

Help us shape the roadmap for the future. Our next feature release will be in October 2026. Mage-OS is community-driven — bug fixes, features, documentation, and testing all make a difference.

• Mage-OS GitHub
• Mage-OS Discord