How to Install Mage-OS on Your Server: Complete Step-by-Step Setup Guide (2026)
Mage-OS is a free, community-maintained ecommerce platform built as an alternative to Magento Open Source. Installing it involves downloading the project with Composer, configuring your database and OpenSearch instance, completing the installation wizard, and deploying the required application files. If you're already running Magento Open Source 2.4.8 or a newer version, you can migrate to Mage-OS using the official migration script instead of creating a new installation from scratch.
With a properly configured server, most developers can complete the installation process in less than an hour.
Introduction
As more businesses look for an open-source ecommerce platform with long-term community support, Mage-OS has become a popular choice among merchants and developers. It offers the flexibility and compatibility of Magento Open Source while being maintained independently by a global community committed to continuous improvements and faster security updates.
Whether you're building a brand-new online store or planning to migrate from Magento Open Source, installing Mage-OS is a straightforward process when your server environment is correctly configured.
In this guide, you'll learn how to install Mage-OS step by step—from checking system requirements and downloading the project to configuring your store and launching your first storefront. We'll also cover migration options and common installation issues to help you avoid unnecessary delays.
Related Articles
What is Mage-OS? Complete Guide to the Community-Driven Open-Source Ecommerce Platform
Top Magento Web Development Companies in 2026
Best Magento Development Agencies in the USA (2026)
What is Mage-OS?
Mage-OS is a community-driven, open-source ecommerce platform developed as an independent distribution of Magento Open Source. It is governed by the non-profit Mage-OS Association, whose mission is to keep the platform open, secure, and accessible for merchants and developers worldwide.
Built as a fork of Magento Open Source, Mage-OS remains fully compatible with the Magento ecosystem. Existing themes, extensions, custom modules, and third-party integrations continue to work without requiring major redevelopment, making migration significantly easier for businesses already using Magento.
One of the biggest advantages of Mage-OS is its community-first approach. Instead of depending on commercial licensing or vendor-controlled development, the platform is maintained by experienced contributors who actively release security updates, bug fixes, and technical improvements to keep stores stable and secure.
For businesses seeking a future-proof ecommerce solution without vendor lock-in, Mage-OS provides the flexibility, scalability, and performance expected from a modern open-source platform.
Mage-OS System Requirements
Before installing Mage-OS, ensure your hosting environment meets the required software specifications. Using the recommended versions of PHP, Composer, MySQL, and OpenSearch helps improve your store's performance, security, and overall stability.
PHP
Minimum Version: 8.3
Recommended Version: 8.5
Composer
Minimum Version: 2.7+
Recommended Version: 2.9.3+
Database
Minimum Version: MySQL 8.0+ or MariaDB 10.6+
Recommended Version: MySQL 8.4 or MariaDB 11.4
Search Engine
Minimum Version: OpenSearch 2+
Recommended Version: OpenSearch 2.19
Operating System
Minimum Requirement: Linux
Recommended Environment: Linux for Production; macOS or Windows using WSL2 or Docker for Local Development
Meeting the recommended specifications helps ensure smoother installation, faster execution, and better long-term performance.
Things to Know Before Installing Mage-OS
Before you begin the MageOS installation process, keep these important recommendations in mind to avoid common setup issues.
Use Linux for Production
Mage-OS is designed to run in Linux production environments. While developers can use macOS or Windows for local testing, it's recommended to use Docker-based environments such as DDEV or Warden, or Windows Subsystem for Linux (WSL2), during development.
OpenSearch Is the Preferred Search Engine
OpenSearch has become the recommended search solution for modern Mage-OS installations. Since Elasticsearch is gradually being phased out across the Magento ecosystem, new projects should use OpenSearch to ensure better compatibility and long-term support.
Verify PHP Extensions
Missing PHP extensions are among the most common reasons why Mage-OS installations fail. Before running the installer, verify that all required extensions are installed and enabled on your server. Spending a few minutes checking your environment can save significant troubleshooting time later.
With your server properly configured, you're now ready to download and install Mage-OS
Step 1: Download the Mage-OS Project
After confirming that your server meets all the required specifications, the first step is to download the Mage-OS Community Edition using Composer.
Open your terminal, navigate to the directory where you want to install your ecommerce store, and run the following command:
composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition
This command downloads the latest stable release of Mage-OS along with all the required packages and dependencies needed to run the platform.
Depending on your internet connection and server performance, the installation may take a few minutes to complete.
Pro Tip: Always use the latest version of Composer to minimize dependency conflicts and ensure a smooth installation.
Step 2: Install Mage-OS
Once Composer finishes downloading the project files, the next step is to install Mage-OS and configure your ecommerce store.
Run the installation command below by replacing the sample values with your own database credentials, domain, and administrator information.
bin/magento install
--base-url=http://yourdomain.com
--db-host=localhost
--db-name=mageos_db
--db-user=db_user
--db-password=db_password
--admin-firstname=Admin
--admin-lastname=User
[email protected]
--admin-user=admin
--admin-password=SecurePassword123
--search-engine=opensearch
--opensearch-host=localhost
--opensearch-port=9200
This installation process will:
Connect Mage-OS to your database.
Configure OpenSearch for catalog indexing.
Generate the application's configuration files.
Create the administrator account.
Prepare your storefront for deployment.
Prefer an Interactive Installation?
If you don't want to provide every parameter manually, simply execute the following command:
bin/magento install
Mage-OS will launch an interactive installation wizard that guides you through each configuration step directly from the command line.
Best Practices During Installation
Use a Strong Administrator Password
Your admin account controls the entire ecommerce store. Choose a unique password that includes uppercase and lowercase letters, numbers, and special characters to reduce security risks.
Verify Your Base URL
Before completing the installation, double-check the --base-url value. An incorrect URL can cause missing images, broken CSS, JavaScript loading issues, and checkout errors.
Check Error Messages Carefully
If the installation stops unexpectedly, don't immediately restart the process. Most installation failures are caused by:
Missing PHP extensions
Incorrect database credentials
OpenSearch connection issues
File permission errors
Resolving these problems first will save considerable troubleshooting time.
Step 3: Compile and Deploy Mage-OS
After the installation completes successfully, you must compile the application and deploy the required static assets before accessing your storefront.
Run the following commands in the same order:
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
Each command plays an important role in completing the Mage-OS deployment process.
setup:upgrade
Purpose: Applies database updates and installs any module changes required by the application.
setup:di:compile
Purpose: Compiles dependency injection (DI) classes to improve application performance and ensure the system runs efficiently.
setup:static-content:deploy -f
Purpose: Generates and deploys static assets such as CSS, JavaScript, images, fonts, and other files required for the storefront.
cache:flush
Purpose: Clears the application cache so that all recent updates and changes are reflected on the storefront and in the Admin Panel.
Skipping any of these commands—especially setup:di:compile or setup:static-content:deploy—may result in missing styles, broken layouts, or a blank storefront.
Once all commands complete successfully, your Mage-OS installation is ready to use.
Upgrade Your Luma Store to Hyvä Without Losing SEO
Still using the default Luma theme?
Migrating to the Hyvä Theme can significantly improve your store's speed, Core Web Vitals, and overall shopping experience while preserving your existing SEO performance.
A professionally planned migration helps retain your current design, functionality, search rankings, and organic traffic while delivering a faster, more modern storefront built for long-term growth.
Migrating from an Existing Magento 2 Store
If your store is already running on Magento Open Source 2.4.8 or a later version, you don't need to create a new installation from the beginning. Mage-OS is built as a drop-in replacement, and the official community migration script allows you to transition from Magento to Mage-OS with minimal effort.
Run the following command to begin the migration:
bash <(curl -s https://raw.githubusercontent.com/mage-os-lab/migrate-m2-to-mageos/refs/heads/main/migrate-to-mage-os.sh)
It is recommended to execute this script in Developer Mode and test the migration on a local or staging environment before applying it to your live website. Once you've verified that everything works correctly, you can perform the migration on your production server during a scheduled maintenance window.
Top 4 Common Mage-OS Installation Issues and Fixes
Installer Stops Due to Missing PHP Extensions
If the installer reports missing PHP extensions, check your installed extensions by running the php -m command and compare the results with the required Mage-OS extensions. Install any missing extensions through your server's package manager and run the installation again.
Search Does Not Return Products After Installation
If your store installs successfully but product search is not working, OpenSearch is usually the cause. Verify that the OpenSearch service is running and make sure the host and port values provided during installation match your server configuration before reinstalling.
Storefront Displays Without Styling
If your storefront loads without CSS or appears broken, the static content deployment may not have completed successfully. Execute the following command again using the -f flag to regenerate the static assets.
bin/magento setup:static-content:deploy -f
Composer Download Fails or Times Out
If Composer fails to download project dependencies or the installation times out, verify that your server has a stable internet connection. Also, ensure you're using Composer version 2.7 or later. If required, update Composer by running:
composer self-update
Why Choose iCreative Technologies for Your Mage-OS Project
iCreative Technologies was one of the early adopters of Mage-OS, allowing our team to gain practical experience with the platform long before its wider industry adoption. We are also a Certified Hyvä Theme Technical Bronze Partner, enabling us to build high-performance Mage-OS storefronts that are fast, lightweight, and optimized for long-term scalability.
As a leading Magento Web Development Services Agency in the USA and a trusted ecommerce technology partner serving businesses across 12+ countries, we help brands successfully migrate from Magento to Mage-OS as well as build new ecommerce stores from the ground up.
With experience across Magento, Mage-OS, Shopware, Shopify Plus, and PrestaShop, our team has successfully delivered 2,000+ ecommerce projects. Our expertise is backed by internationally recognized CMMI Level 3 and ISO 9001 certifications, reflecting our commitment to quality, structured development processes, and reliable project delivery.
Whether you're considering Mage-OS for a new ecommerce project or planning to migrate an existing Magento store, iCreative Technologies can assist with project planning, technical migration, Hyvä Theme implementation, custom development, and performance-focused ecommerce solutions.
Download Mage-OS in Minutes!
Ready to get started with Mage-OS?
Download the latest stable version directly from the official Mage-OS download page and begin building your next ecommerce project with a powerful, community-driven open-source platform.