Quick start – Up and running with macOS in minutes
Are you using Ubuntu, Fedora, or any other Linux distribution and urgently need a macOS environment to check layouts in Safari? Or do you simply want to test build a Swift snippet without owning a Mac? Try this command. I assume you have Docker installed and your machine supports KVM.
docker run -it \
--device /dev/kvm \
-p 50922:22 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:autoThe command above will automatically pull the macOS Catalina image (around 2.3GB) and launch the interface right on your Linux screen. Instead of spending an hour configuring ISO files in VirtualBox, you can just sit back, enjoy a cup of coffee, and you’re done. Pretty convenient, right?
Why Docker-OSX is the “Holy Grail” for Developers?
In the past, mentioning Hackintosh immediately brought to mind the headache of partitioning hard drives or editing EFI files. Using VirtualBox often resulted in sluggish performance and frustrating lag.
Docker-OSX completely solves these pain points. It combines the power of QEMU and KVM (Kernel-based Virtual Machine) while being neatly packaged in Docker. Here are 3 features I find extremely valuable:
- Near-native performance: Thanks to KVM, the CPU is passed through directly. Typing and opening apps feel much smoother than in VirtualBox, and code build speeds are about 30% faster.
- Infrastructure as Code management: You can delete and recreate, or clone a clean macOS environment with a single command line.
- Integrated X11 Forwarding: The macOS window appears like a normal app on your Linux desktop, without feeling isolated.
In my homelab system running Proxmox VE (managing 12 VMs), I always dedicate a Linux node for Docker-OSX. This is an ideal playground for testing automation scripts and Jenkins build agents before real deployment.
Prerequisites
To ensure the VM runs smoothly and avoid the “stuck on Apple logo” error, your computer needs to meet a few requirements:
1. Enable virtualization in BIOS
Enter BIOS/UEFI, find and Enable Intel VT-x or AMD-V. Then verify with the command:
kvm-okIf you see the line “KVM acceleration can be used”, you’re ready. If the command isn’t found, install the cpu-checker package.
2. Install Docker and supporting libraries
On Ubuntu or Debian, install the environment using the following command:
sudo apt update
sudo apt install qemu qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager docker.io -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
sudo usermod -aG kvm $USERPro tip: Remember to log out and log back in for the permission settings to take effect.
Detailed installation guide for various macOS versions
Depending on your needs, choose the appropriate version. The author sickcodes provides everything from High Sierra to the latest Ventura or Sonoma.
Installing macOS Monterey (For modern Xcode support)
If your goal is to build the latest iOS apps, you’ll need Monterey or newer. The command below creates a 40GB virtual hard drive and begins the installation process:
docker run -it \
--device /dev/kvm \
-e "RAM=6" \
-e "CORES=4" \
-p 50922:22 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:montereyQuick parameter breakdown:
RAM=6: Assigns 6GB of RAM (I recommend at least 4GB).CORES=4: Number of CPU cores assigned to the VM.-p 50922:22: Forwards the SSH port to control the Mac from your Linux terminal.
Important note: When the installation screen appears, you must go to Disk Utility to format the virtual drive (usually QEMU HARDDISK) to APFS format before clicking “Reinstall macOS”.
Performance optimization for a smooth experience
Now that it’s installed, here are 3 steps to ensure stable long-term use.
1. Persistent Data Storage (Persistence)
By default, when a container is deleted, all data inside macOS is lost. To keep your files and configurations, mount a folder from the host machine as the VM’s drive:
docker run -it \
--device /dev/kvm \
-v /home/user/macos_data:/var/lib/libvirt/images \
-p 50922:22 \
sickcodes/docker-osx:auto2. Connecting iPhone/iPad to the virtual machine
This is a feature I really love. To debug apps directly on an iPhone, use lsusb to find the device ID, then add the parameter to the run command. The easiest way is using an environment variable:
# Example: Pass-through a specific USB device
-e "EXTRA=-device usb-host,hostbus=1,hostport=3"3. Headless mode for CI/CD
If you’re only using it as a build server, there’s no need for a GUI consuming resources. Remove the DISPLAY variable and run in the background:
docker run -d \
--device /dev/kvm \
-p 50922:22 \
sickcodes/docker-osx:autoNow, you can simply ssh -p 50922 user@localhost to interact with the Mac terminal.
Real-world experience and important notes
After over a year of using Docker-OSX professionally, here is some practical advice:
- Avoid using personal iCloud: Docker-OSX can spoof Serial Numbers for iMessage, but there is a real risk of Apple banning your primary account. It’s best to create a dummy Apple ID for testing.
- Prioritize NVMe drives: The difference in macOS load speeds between a standard SSD and NVMe is significant. On NVMe, the VM takes less than 20 seconds to boot to the home screen.
- Network Issues: If the VM has no internet access, check
bridge-utils. Sometimes Docker conflicts with iptables rules on your Linux system.
The initial setup might seem a bit complicated command-wise. However, once you’re up and running, you’ll find it much more stable and faster than traditional VMs. This solution has saved me a considerable amount of money compared to buying a Mac Mini just for minor compilation tasks.
Feel free to dive in and experiment. If you encounter issues during docker pull or get stuck on the Apple logo, leave a comment below and I’ll help out.
