Run macOS Inside Docker with dockur/macos: A Practical Guide for Developers

Key Takeaways: Running macOS inside Docker with dockur/macos gives you a reproducible, browser-accessible macOS environment for development, testing, and CI/CD using just a few Docker commands.

What is dockur/macos and why should you care?

dockur/macos is an open-source project that packages a full macOS virtual machine inside a Docker container using QEMU/KVM, with sane defaults for firmware, disk, and devices. Instead of manually wiring QEMU, EFI firmware, and VNC, you run a single Docker image (or Docker Compose service) and get a macOS instance you can access directly from your browser.

The project supports multiple macOS versions and can automatically download the installer for you on first run, making it easy to spin up fresh macOS environments for development, testing, or demos. This is especially useful if you need macOS for iOS/macOS builds, cross-platform testing, or temporary sandboxes on a Linux host.

Official links you should bookmark:

GitHub repo: dockur/macos
Docker image: dockurr/macos on Docker Hub

Key benefits of running macOS in Docker

Running macOS via Docker is more than just a neat hack; it solves real-world problems:

Reproducible dev/test environments: Treat your macOS setup as code (compose file + env vars) so every teammate or CI runner gets the exact same environment.
CI/CD integration: On a KVM-enabled Linux host, you can spin up macOS containers inside your pipelines to build and test macOS/iOS apps automatically.
Safe sandboxing: All changes stay inside the container volume; experiment freely with tools, scripts, or system tweaks without polluting your main system.
Horizontal scaling: Run multiple parallel macOS instances on a beefy server or homelab to handle concurrent build/test jobs.

Compared to traditional “install macOS on a spare Mac” setups, this approach is easier to automate, destroy, and recreate on demand.

System requirements and licensing caveats

Before you start, make sure your host and setup meet these requirements:

Host OS:
Best: Linux with KVM support (bare metal, or a VM with nested virtualization enabled).
Possible: Windows 11 with WSL2 + Ubuntu, if your hypervisor and CPU support nested virtualization. Expect more tuning.
CPU and virtualization:
CPU with hardware virtualization (Intel VT‑x, AMD‑V) enabled in BIOS/UEFI.
KVM must be available to containers via /dev/kvm to get acceptable performance.
Memory and storage:
At least 4 GB RAM for the macOS VM; 8 GB or more is recommended for smoother usage.
Disk space for the macOS image and your projects (tens of GBs is typical).
Container runtime:
Docker Engine or compatible runtime (e.g. Podman) with permission to use devices like /dev/kvm and /dev/net/tun.

On the licensing side, you must comply with Apple’s macOS EULA, which places restrictions on where and how macOS can be virtualized. Whether your usage is allowed depends on your hardware and use case; you are responsible for verifying that your setup respects Apple’s terms.

Quick start using Docker CLI

For a quick local test, you can launch macOS directly via docker run on a Linux host with KVM:

docker run -it --rm --name macos \
  -e "VERSION=14" \
  -p 8006:8006 \
  --device=/dev/kvm \
  --device=/dev/net/tun \
  --cap-add NET_ADMIN \
  -v "${PWD:-.}/macos:/storage" \
  --stop-timeout 120 \
  dockurr/macos

Key flags explained:

-e "VERSION=14" selects macOS 14 (Sonoma); you can switch to other supported versions as listed in the repo/docs.
-p 8006:8006 exposes the built-in web-based viewer on port 8006 for browser access.
--device=/dev/kvm enables hardware acceleration through KVM, which is critical for performance.
--device=/dev/net/tun plus --cap-add NET_ADMIN allow the VM to configure its own virtual networking.
-v "${PWD:-.}/macos:/storage" mounts a host directory to persist disks and configuration across container restarts.

On first launch, the image will download the macOS installer for the chosen version, which may take a while depending on your network.

Stable setup with Docker Compose

For long-term use or team sharing, Docker Compose is the better approach. You can describe your macOS environment declaratively and commit it to your repo.

Example docker-compose.yml:

services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      VERSION: "15"
      RAM_SIZE: "8G"
      CPU_CORES: "4"
      DISK_SIZE: "256G"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - "8006:8006"
      - "5900:5900/tcp"
      - "5900:5900/udp"
    volumes:
      - ./macos:/storage
    restart: unless-stopped
    stop_grace_period: 2m

Important fields:

VERSION: macOS version (for example, 11 for Big Sur, 14 for Sonoma, 15 for Sequoia, depending on image support).
RAM_SIZE, CPU_CORES, DISK_SIZE: resource allocation for the guest macOS VM.
ports:
8006:8006 for the web-based desktop viewer.
5900 for VNC (TCP/UDP) if you prefer a native VNC client.
volumes: ./macos stores disk images and configuration, making the VM state persistent and easy to back up.

Bring the VM up with:

docker compose up -d

This “infrastructure as code” style is perfect for teams; you can replicate the same macOS environment anywhere Docker and KVM are available.

First-time setup: installing macOS in the container

Once the container is running, open your browser and go to:

http://localhost:8006

You should see the macOS installer boot screen via the web-based viewer. Full installer flow:

Select language and keyboard layout.
Open Disk Utility, choose the largest Apple Inc. VirtIO Block Media disk, and erase it as APFS with your preferred name.
Close Disk Utility.
Choose Reinstall macOS and select the APFS volume you just created.
Let the installer copy files and reboot as needed.

After installation completes, you’ll go through the usual macOS setup assistant (region, Apple ID, user account, etc.). From that point on, you have a fully functional macOS desktop running inside a Docker container.

Managing your macOS container: lifecycle, resources, backups

Start/stop and logs

With Compose:

docker compose ps
docker compose stop macos
docker compose start macos
docker compose logs -f macos

With plain Docker:

docker ps
docker stop macos
docker start macos
docker logs -f macos

These commands give you a normal container lifecycle, while the VM state itself lives in the mounted /storage directory.

Tuning CPU, RAM, and disk

To change VM resources, update the environment variables in your compose file:

environment:
  VERSION: "15"
  RAM_SIZE: "16G"
  CPU_CORES: "8"
  DISK_SIZE: "512G"

Then recreate:

docker compose down
docker compose up -d

The backing disk image typically uses a sparse/dynamic format (like qcow2), so the logical DISK_SIZE can be larger than the physical disk used initially, but keep an eye on real disk usage as the VM fills up.

Persisting and backing up macOS

All VM state (system disk, user data, configuration) is stored in the volume you mapped to /storage (for example, ./macos).
Backup workflow:

Stop the container (docker compose stop macos).
Archive the ./macos directory (zip, tar, or rsync to another machine).
To restore, copy the archive back and run the container with the same compose configuration.

This makes macOS snapshots and migrations straightforward.

Real-world use cases for developers and teams

Here are some concrete use cases where dockur/macos shines:

iOS/macOS CI builds from Linux:
Use a Linux build server with KVM to run dockur/macos as part of your pipeline, install Xcode inside the VM, and build/sign iOS/macOS apps programmatically.
Customer demos in a browser:
Pre-install your tools inside the macOS VM, expose the web viewer via a reverse proxy with authentication, and let clients explore a “live macOS desktop” from their browser without giving direct access to hardware.
Cross-platform testing farm:
Combine dockur/macos with dockur/windows to run macOS, Windows, and Linux environments side by side on the same host or cluster for full cross-platform QA.
Security research and sandboxing:
Treat the macOS container as a disposable environment to test security tools, scripts, and configuration changes that you don’t want touching your main machine.

For content creators, this setup also makes an excellent blog/Youtube topic: “Running macOS in Docker on Linux/WSL for iOS developers.”

Performance tuning and current limitations

Even with KVM acceleration, there are some limitations you should keep in mind:

KVM and nested virtualization dependency:
If you’re running Docker inside another VM without nested virtualization, performance can be poor or the VM might not start at all.
Limited GPU acceleration:
GPU passthrough is non-trivial; by default you’ll rely mainly on CPU rendering, which is fine for IDEs, builds, and moderate UI usage, but not ideal for heavy graphics workloads.
Disk and I/O:
Place your /storage volume on a fast SSD, especially if you build large projects or install many tools. HDDs will quickly become a bottleneck.
Networking quirks:
Some users report having to tweak the compose file or host firewall to fix connectivity issues inside macOS. Follow the examples from the official repo and ensure TUN and NET_ADMIN are configured correctly.

FAQ: common questions about dockur/macos

Can I run dockur/macos on Windows 11 with WSL2?

Yes, as long as your hypervisor and CPU support nested virtualization and you can expose /dev/kvm inside WSL2’s Linux environment. Users have reported successfully running Big Sur and later by adjusting the VERSION, RAM_SIZE, and CPU_CORES environment variables and ensuring KVM is functional.

Can I use dockur/macos to build App Store‑ready iOS apps?

Technically, yes: once Xcode and your signing setup are configured inside macOS, you can build and sign iOS apps. However, you still need to verify that this usage complies with Apple’s EULA and App Store policies, as they may have specific requirements regarding virtualization and build environments.

How is dockur/macos different from Docker-OSX?

Docker-OSX pioneered running macOS in Docker, but dockur/macos focuses on a streamlined experience with KVM acceleration, a browser-based viewer on port 8006, and concise Docker CLI/Compose/Kubernetes snippets for production-like setups. dockur/macos is currently one of the most active and user-friendly projects in this space.

Can I run multiple macOS containers at once?

Yes. As long as your host has enough CPU, RAM, and I/O capacity, you can start multiple macOS containers in parallel, each mapped to different ports (for example, 8006, 8007, 8008). This is a powerful way to build a small “macOS farm” for parallel CI jobs or testing sessions.

With dockur/macos, you can turn a single KVM-capable host into a flexible macOS lab for development, testing, demos, and CI/CD—fully described as code, easy to reproduce, and accessible from any browser.