Setting up a local Magento 2 development environment on macOS is a critical step for developers building custom themes, extensions, or full e-commerce stores. In 2025, the landscape has shifted strongly toward containerized setups, with Docker emerging as the preferred method for its reliability, consistency, and performance across both Intel and Apple Silicon machines.

Native installations involving Homebrew, manual PHP configuration, and separate services often lead to version conflicts, permission issues, and slow file synchronization—especially on M-series chips. Docker eliminates these problems by packaging all dependencies into isolated containers that mirror production environments closely.

This guide focuses on the widely adopted docker-magento configuration, a community-maintained project optimized specifically for Magento 2 development. It includes built-in tools for fast file syncing on macOS, Xdebug support, and streamlined CLI commands, making it the go-to choice for thousands of Magento developers worldwide.

By the end of this tutorial, you will have a fully functional Magento 2 instance running locally, complete with admin access, sample data options, and best practices for daily development workflows.

Why Choose Docker for Magento 2 on macOS

Docker provides numerous advantages that make it superior to traditional local stacks like MAMP or native Homebrew setups. Here are the key benefits:

Consistency across teams: Every developer uses identical container images, eliminating “it works on my machine” issues. This ensures smooth collaboration whether team members are on Intel or Apple Silicon Macs.
Performance optimization for macOS: The setup includes tools like Mutagen or native VirtioFS for dramatically faster file synchronization compared to default Docker volume mounting, which can otherwise slow page loads to unacceptable levels.
Easy dependency management: Magento 2 requires specific versions of PHP, MySQL, Elasticsearch/OpenSearch, Redis, Varnish, and Composer. Docker handles all versioning automatically, preventing conflicts with system-level installations.
Production-like environment: Containers replicate real server conditions more accurately than localhost stacks, helping catch issues early before deployment.
Simple updates and cleanup: Spin up new instances for different Magento versions in minutes, and tear everything down with a single command when finished.
Built-in developer tools: Integrated Xdebug, Mailhog for email testing, and easy Magento CLI access streamline debugging and testing workflows.
Apple Silicon native support: All images include arm64 variants, ensuring optimal performance on M1, M2, and M3 chips without Rosetta emulation overhead.
Active community maintenance: The docker-magento project receives regular updates to support the latest Magento patches and PHP versions.

These advantages make Docker not just convenient but essential for professional Magento 2 development in 2025.

Prerequisites

Before beginning, ensure your system meets the minimum requirements and has the necessary tools installed.

System Requirements

– macOS 12 (Monterey) or later
– At least 8 GB RAM (16 GB or more recommended for smooth performance)
– 20 GB free disk space
– Apple Silicon (M1/M2/M3) or Intel processor

Required Software

Docker Desktop for Mac (latest stable version)
Git
Homebrew (for optional Mutagen installation on older setups)
Terminal access (default Terminal or iTerm2 recommended)

Most modern Macs already have Git pre-installed. If not, installing Xcode Command Line Tools will add it.

Step 1: Install Docker Desktop

Start by downloading and installing Docker Desktop, the foundation of your local environment.

Visit the official Docker website and download Docker Desktop for Mac. Choose the appropriate version: Apple Silicon for M-series chips or Intel for older machines. The installer will guide you through the process.

After installation, open Docker Desktop from your Applications folder. Grant any requested permissions for privileged access. Docker will start automatically and appear in your menu bar.

Verify the installation by opening Terminal and running:

docker –version

docker compose version

You should see version information displayed. If Docker asks to enable VirtioFS for better performance, accept it—this significantly improves file syncing on newer macOS versions.

Step 2: Clone the docker-magento Repository

The docker-magento project provides pre-configured Docker Compose files and helper scripts tailored for Magento 2.

Open Terminal and create a directory for your projects:

mkdir ~/magento-projects && cd ~/magento-projects

Clone the repository:

git clone https://github.com/markshust/docker-magento.git

cd docker-magento

This repository contains everything needed: container definitions for PHP, Nginx, MySQL, Elasticsearch, Redis, and more.

The project is actively maintained and supports the latest Magento 2.4.x releases as of 2025.

Step 3: Configure the Environment

Copy the example override file to enable custom settings:

cp compose.override.yml.example compose.override.yml

This file allows customization of ports, volumes, and services without modifying the core configuration.

Optionally, edit compose.override.yml in your preferred code editor to adjust ports if you have conflicts (e.g., if port 80 is already in use).

For optimal performance on macOS, the configuration automatically detects and uses the best available file synchronization method.

Step 4: Start the Containers

Bring up the Docker environment:

bin/start

This command starts all required services in the background. The first run will download necessary Docker images, which may take several minutes depending on your internet speed.

Once complete, verify containers are running:

bin/status

You should see all services listed as healthy.

If you encounter any issues with file synchronization, the setup includes fallback options that automatically optimize for your system.

Step 5: Install Magento 2

Now install the Magento 2 application itself using the provided setup script:

bin/setup

The script will prompt you for:

Domain name (e.g., magento.test—use something simple)
Magento edition (community or enterprise)
Magento version (default is latest stable, typically 2.4.7-p3 or newer in 2025)
Admin credentials
Whether to install sample data

Accept defaults where appropriate for a standard setup. Choose to install sample data if you want pre-populated products and categories for testing.

The script handles everything: Composer create-project, database setup, Magento installation command, cache configuration, and host file suggestions.

For a specific version, you can pass it directly:

bin/setup magento.test –magento-version=2.4.7-p3

Installation typically takes 10–20 minutes on a modern Mac.

Step 6: Access Your Magento Site

Add the local domain to your hosts file:

echo “127.0.0.1 magento.test” | sudo tee -a /etc/hosts

Open your browser and navigate to http://magento.test (or whatever domain you chose).

You should see the Magento storefront. Access the admin panel at http://magento.test/admin using the credentials you set during setup.

The site is now ready for theme development, extension installation, or custom module creation.

Troubleshooting Common Issues

Containers fail to start: Check Docker Desktop is running and has sufficient allocated resources (at least 4 CPU cores and 8 GB RAM recommended). Restart Docker if needed.
Slow page loads: Ensure VirtioFS is enabled in Docker settings. If still slow, run bin/mutagen for enhanced synchronization on older setups.
Port conflicts: Edit compose.override.yml to change exposed ports (e.g., map host port 8080 to container 80), then run bin/restart.
Elasticsearch connection errors: Wait a few minutes after starting containers for services to fully initialize. Run bin/restart elasticsearch if needed.
Permission denied errors: Run bin/fixperms to correct ownership inside containers.
Out of memory errors: Increase Docker Desktop memory allocation in Preferences > Resources.
Apple Silicon image pull issues: The images include multi-arch support; if problems persist, force a clean rebuild with bin/stop && bin/start –build.

Pro Tips

– Use bin/magento for all Magento CLI commands—it automatically executes inside the PHP container.
– Enable Xdebug by running bin/xdebug on for seamless PHPStorm or VS Code debugging.
– Test emails locally with Mailhog at http://magento.test:8025.
– Switch Magento versions easily by stopping containers, editing the setup command, and reinstalling.
– Backup your database with bin/mysql-dump before major changes.
– Keep everything updated with regular git pull in the docker-magento directory.
– For team consistency, commit your compose.override.yml to version control.

Frequently Asked Questions

Is this setup compatible with the latest macOS versions?
Yes, it works excellently on macOS Sonoma and Ventura, with full support for the newest M3 chips.

Do I need to install PHP or MySQL separately?
No—everything runs in containers, keeping your system clean.

Can I use this for existing Magento projects?
Absolutely. Place your source code in src/, run bin/composer install, and import your database.

What if I prefer the official Adobe Docker setup?
While possible, the community docker-magento project offers more developer-friendly features and better macOS performance.

How do I completely remove everything?
Run bin/stop && bin/rm to delete containers and volumes.

Is sample data installation recommended?
Yes for learning or testing themes/extensions; skip for production-like clean installs.

Conclusion

Following this guide gives you a professional-grade Magento 2 development environment on macOS that is fast, reliable, and closely aligned with modern best practices. Docker eliminates the traditional pain points of local setup while providing the flexibility needed for serious development work. With your local store now running, you can confidently build, test, and deploy custom Magento solutions. Regular updates to both Docker Desktop and the docker-magento repository will keep your environment current through 2025 and beyond, ensuring continued productivity and performance.