November 14, 2023

Mage-OS 1.0 is here

Yireo Blog Post

It actually already came out a month ago (October 9th): Mage-OS 1.0.0 (quickly followed by 1.0.1 because of Magento 2.4.6-p3). Woohoo, the distribution is here. But what does it mean? Will it break things? Should you upgrade? Is the world coming to an end?

Quick intro to Mage-OS

In case you missed the memo, Magento has been taken over by Adobe and since that take-over uncertainty on the future of Magento Open Source has been growing. A group of Magento community people wrote a letter to Adobe (and the Magento Association) to set an ultimatum. That ultimatum (which included a gentle suggestion to remove the false statement that Magento Open Source is now replaced with Adobe Commerce) passed and this led the same group of people to found Mage-OS as a foundation.

The distribution

This Mage-OS foundation has worked hard to clone the Magento Open Source sources as they can be found on GitHub, extract version information (because that's locked up in the Adobe release cycle) and get a functioning mirror up and running. No real changes, just a copy. However, I've been telling people from the start that things would get more interesting at the very moment when a tiny little fix would be in the Mage-OS clone and not in Magento Open Source. At that very moment, the clone would start to live a new life and would start to have an added value compared to Magento Open Source itself.

This moment was October 9th 2023. At that moment, a first release was made of Mage-OS version 1.0. Including some features that are not in Magento Open Source 2.4.6 (as of yet).

What is different?

The release notes of 1.0.0 are not large (and 1.0.1 was only there to include the 2.4.6-p3 security fixes). A couple of packages were removed (similar to my work in the yireo/magento2-replace-tools), a Maestro Domestic CC fix was included, some admin session size fix.

But to me, more noteworthy are the UI changes in the Magento Admin Panel: Once you head-over to the backend, you no longer see the Magento logo, but instead the Mage-OS logo. And various changes have been made in the CSS as well, to give the admin a bit of a different vibe. Cosmetic perhaps, but it shows a statement that Mage-OS is different.

And a feature to allow for faster category product counts in the Admin Panel: PR 37350. This PR was made to the Magento Open Source repository in April this year, but removed because of too many test failures. Normally, this would mean that such a PR ends up in oblivion, without anyone benefiting. In this case, this PR is included in Mage-OS. I personally see this very change as the real marker of something new.

Composer packages under vendor/mage-os/

One of the noteworthy changes for me was to see that all of the Magento packages (framework, modules, themes) were moved from the composer namespace magento to mage-os. This makes sense, because Magento is now longer is the vendor, Mage-OS is. However, this brought up an interesting side-effect: Changing the vendor name means changing the composer package-names. For instance, the package magento/framework has now become mage-os/framework (even though the source code is still identical).

But what about 3rd party modules that depend on magento/framework. This is where a little trick is played. The Mage-OS mirrors are generated via a script generate-mirror-repo-js which essentially copy sources from Magento its GitHub repository. However, the composer.json file of each individual package is generated on the fly: First, to allow for the new vendor name (magento to mage-os). Second, to add a replace section which refers to the old Magento composer name, indicating that any requirement for the original Magento name should be rewritten to the new Mage-OS name.

For example. the module magento/module-catalog-widget is rewritten to mage-os/module-catalog-widget. Its generated composer.json file is kind-of a duplicate with the original composer.json file with a few changes: The name is different. Its dependencies with magento/* have been rewritten to mage-os/*. And it has a replace of magento/module-catalog-widget to allow for the original package to be replaced with mage-os/module-catalog-widget.

Because of this, any third-party package is compatible with Mage-OS, as long as that third-party package is compatible with the Magento version that Mage-OS replaces. For instance, Mage-OS 1.0.1 is a replacement of Magento 2.4.6-p3. But you will not be able to use Magento modules in Mage-OS 1.0 if those modules are only compatible up to Magento 2.3.7 (which should be abandonded anyway).


The word is out: Mage-OS is now a real thing that you can install and play with. It still resembles Magento, but slowly new additions are made. And I definitely believe that on the long run, it will be worth more to install Mage-OS than Magento Open Source.

Posted on November 14, 2023

About the author

Author Jisse Reitsma

Jisse Reitsma is the founder of Yireo, extension developer, developer trainer and 3x Magento Master. His passion is for technology and open source. And he loves talking as well.

Sponsor Yireo

Looking for a training in-house?

Let's get to it!

We don't write too commercial stuff, we focus on the technology (which we love) and we regularly come up with innovative solutions. Via our newsletter, you can keep yourself up to date on all of this coolness. Subscribing only takes seconds.

Do not miss out on what we say

This will be the most interesting spam you have ever read

We don't write too commercial stuff, we focus on the technology (which we love) and we regularly come up with innovative solutions. Via our newsletter, you can keep yourself up to date on all of this coolness. Subscribing only takes seconds.