Migration Guide
Migrating from Magento Open Source to Mage-OS is straightforward and typically takes under 30 minutes. Your existing extensions, themes, and customizations will continue to work with little or no changes needed.
Why Migrate to Mage-OS?
Mage-OS is built on the same Magento Open Source foundation you already trust, enhanced with community-driven improvements.
Enhanced Performance
Optimized caching and database queries for faster page loads and better user experience.
Faster Security Patches
Community-accelerated security updates, often released ahead of upstream Magento.
PCI DSS 4.0 Ready
Built-in compliance settings for modern payment security requirements.
AI-Powered Translation
Automatic content translation using DeepL, OpenAI, or Google Gemini.
Theme Optimization
Back/forward cache support and speculative preloading for better Core Web Vitals.
No Vendor Lock-in
Fully open source with transparent, community-led governance.
Pre-Migration Checklist
Complete these items before starting your migration
Backups
pub/media directory).env, app/etc/env.php)Environment
composer --version)Recommended
Migration Process
Follow these four steps to migrate your Magento store to Mage-OS
Step 1: Create Backup
Back up your database and files before making any changes. This ensures you can rollback if needed.
Step 2: Switch Repository
Add the Mage-OS repository and swap the product packages from Magento to Mage-OS using Composer.
Step 3: Run Upgrade
Execute setup:upgrade, compile DI, deploy static content, reindex, and flush caches.
Step 4: Verify Installation
Confirm Mage-OS version and test your storefront and admin panel to ensure everything works correctly.
1 Create Backup
# Backup database
mysqldump -u username -p database_name > backup.sql
# Backup files
tar -czvf magento-backup.tar.gz /path/to/magento2 Switch to Mage-OS Repository
Use the official migration script to automate the repository switch and dependency updates. Run this command from your Magento root directory:
cd /path/to/your/magento
bash <(curl -s https://raw.githubusercontent.com/mage-os-lab/migrate-m2-to-mageos/refs/heads/main/migrate-to-mage-os.sh)3 Run Upgrade
# Run setup upgrade
bin/magento setup:upgrade
# Compile DI
bin/magento setup:di:compile
# Deploy static content
bin/magento setup:static-content:deploy -f
# Reindex
bin/magento indexer:reindex
# Flush cache
bin/magento cache:flush4 Verify Installation
# Check version
bin/magento --version
# Should output: Mage-OS 2.x.xCompatibility
Mage-OS is designed for seamless migration. Your existing Magento ecosystem remains fully functional.
Extensions
Marketplace extensions, third-party payment gateways, shipping providers, custom modules, and API integrations all continue to work.
Themes
Luma, Blank, custom themes, third-party themes like Hyva and Porto, and headless PWA frontends are fully compatible.
Customizations
Custom API integrations, event observers, plugins, layout/template overrides, and CLI commands work without changes.
Production Migration
For production environments, use a staged approach
Clone Environment
Clone your production to a staging environment first.
rsync -avz production/ staging/Test on Staging
Perform migration on staging and thoroughly test:
- Checkout flow
- Admin panel functionality
- Third-party integrations
- Custom functionality
Schedule Maintenance
For the final switchover:
- Enable maintenance mode
- Sync any database changes
- Perform migration
- Test critical paths
- Disable maintenance mode
Post-Migration
Congratulations on migrating to Mage-OS! Complete these verification steps.
Verify Your Installation
bin/magento --versionTest Critical Functionality
Explore New Mage-OS Features
Mage-OS 2 includes powerful new capabilities:
Admin > Stores > Configuration > Security
Admin > Stores > Configuration > Services > AI Translation
Enable bfcache and speculative loading in Advanced settings
CMS Widget support with live previews
Troubleshooting
Solutions for common migration issues
Need Help?
The Mage-OS community is here to support your migration journey
Community Support (Free)
- Discord - Real-time help
chat.mage-os.org
- GitHub Discussions
Ask questions and share solutions
- Developer Documentation
Comprehensive technical guides
Professional Support
For enterprise migrations or complex environments, our partner network offers:
- Dedicated migration assistance
- Custom development and integration
- Ongoing support and maintenance
Next Steps
Continue your Mage-OS journey
