Self-hosting macOS virtual machines has become an area of interest for developers, QA teams, and IT professionals seeking a contained testing environment. The dockurr/macos project provides a streamlined method to run macOS within Docker using QEMU and KVM acceleration. This article explains the setup process, key requirements, and important compliance considerations.
Apple’s licensing terms only permit macOS to be virtualised on Apple-branded hardware. Running a macOS guest on non-Apple devices constitutes a licence breach. Organisations intending to deploy this workflow must ensure hosts are Apple hardware to remain compliant with Apple’s End User Licence Agreement (EULA).
The container relies on hardware virtualisation and networking support. Before deploying, verify:
These prerequisites enable QEMU to provide near-native CPU performance.
A standard docker-compose.yml file provisions the macOS guest. An example:
services: macos: image: dockurr/macos container_name: macos environment: VERSION: "15" # macOS Sequoia RAM_SIZE: "20G" CPU_CORES: "8" DISK_SIZE: "128G" devices: - /dev/kvm - /dev/net/tun cap_add: - NET_ADMIN ports: - "8006:8006" # Web console - "5900:5900/tcp" # VNC - "5900:5900/udp" volumes: - ./macos:/storage restart: always stop_grace_period: 2mPersistent storage, including the VM disk, is maintained in the ./macos directory. Resource allocation can be customised for RAM, CPU, and disk size.
Once deployed, the installation proceeds through Apple’s recovery utilities:
Run docker compose up -d to launch the service.
docker compose up -dAccess via browser at http://localhost:8006 or through a VNC client on port 5900.
In Disk Utility, erase the largest "VirtIO Block Media" disk and format as APFS.
Choose "Reinstall macOS" and complete the guided setup. The installer will download files and reboot several times.
The installation can take considerable time depending on network throughput.
These optimisations enhance usability but performance will still be below bare-metal macOS.
Common issues include:
Following the GitHub project’s issue tracker provides current solutions to version-specific problems.
The dockurr/macos image delivers a practical framework for running macOS virtual machines within Docker. When executed on Apple hardware, it provides a compliant, cost-effective option for testing, training, and software validation. With proper configuration, teams can achieve reliable macOS virtualisation backed by KVM performance and persistent containerised management.