# dockur/macos: running macOS inside a Docker container on Linux with KVM

> The project wraps QEMU, OpenCore and a web viewer into a single container that installs macOS from Apple's recovery images. It is a Linux-and-KVM proposition, not a way to get macOS on a Windows 10 or Docker Desktop machine.

**dockur/macos** — MacOS inside a Docker container.

- Repository: https://github.com/dockur/macos
- Stars: 21,591 · Forks: 1,132
- Language: Shell
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/dockur-macos

## What dockur/macos solves, and for whom

Apple's licence ties macOS to Apple hardware, and the practical route to a second macOS machine has usually been a spare Mac, a cloud Mac instance, or a hand-built QEMU setup with OpenCore. dockur/macos packages the third option as a container image. The repository describes itself as "MacOS inside a Docker container", and the Dockerfile shows the shape of that claim: the image starts from qemux/qemu:7.50, adds OpenCore, VMHide, the LongQT OpenCore ISO and the OVMF firmware files from kholia/OSX-KVM, then copies the src and assets directories into the image. The audience is engineers who already run Docker on a Linux box and want a macOS guest they can start, stop and delete like any other service. It is not aimed at people who want macOS as their primary desktop, and it is not a way around Apple's licence terms; the project ships under MIT, which covers its own code, not the operating system it installs.

## Inside the container: QEMU, OpenCore and a browser viewer

The base image is qemux/qemu:7.50, so the container is a QEMU virtual machine with a thin management layer. Firmware comes from the OSX-KVM project: OVMF_CODE.fd and several OVMF_VARS variants are added at fixed paths under /usr/share/OVMF, and the Dockerfile pins a specific OSX-KVM commit rather than tracking a branch. OpenCore supplies the bootloader and, through its macserial utility, the serial numbers that make the guest look like real hardware; VMHide is fetched as a release zip and LongQT-OpenCore as an ISO. The container volume is /storage, and the compose file binds ./macos to it, so the disk image and installation files live on the host. Networking is handed to the host kernel through /dev/net/tun plus the NET_ADMIN capability. Control happens over HTTP: port 8006 serves the web viewer, and 5900 is exposed for VNC over both TCP and UDP. The README's walkthrough is entirely inside that viewer, from the recovery download to Disk Utility, Reinstall macOS and the Migration Assistant prompt.

## Installing dockur/macos and completing a first boot

The README gives a compose file as the primary route. It requests /dev/kvm and /dev/net/tun, adds NET_ADMIN, maps 8006 and 5900, and mounts ./macos at /storage. The VERSION variable selects the release; the README's table lists 15 (Sequoia, the default), 14 (Sonoma), 13 (Ventura), 12 (Monterey) and 11 (Big Sur), and a note adds that macOS 26 (Tahoe) can be selected but "is not recommended yet, as it runs very slow for some unknown reason".

```yaml
services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      VERSION: "15"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
      - 5900:5900/tcp
      - 5900:5900/udp
    volumes:
      - ./macos:/storage
    restart: always
    stop_grace_period: 2m
```

A single docker run command is offered as an equivalent, with VERSION=14 and a 120 second stop timeout, and the README also points at a kubernetes.yml manifest and a GitHub Codespaces badge. After the container starts, open http://127.0.0.1:8006/ in a browser. Expect a black screen with a progress bar while the installer downloads, then the macOS recovery menu. The README's sequence is: open Disk Utility, select the largest "Apple Inc. VirtIO Block Media" disk, erase it as APFS, close the window, click Reinstall macOS, pick the disk you created, then answer the region, language and keyboard prompts. At the Migration Assistant choose "Not now"; at the Apple ID screen choose "Set Up Later" and skip; then create a local account. Nothing in the README suggests this is quick, and the download plus install is the slowest part of the process.

Resource defaults matter before you start. The Dockerfile sets RAM_SIZE to 4G and CPU_CORES to 1, and the README states the default disk is 64 GB. To change them, add environment variables:

```yaml
environment:
  RAM_SIZE: "8G"
  CPU_CORES: "4"
```

The README carries a warning for AMD hosts: avoid multiple CPU cores and more than 8 GB of RAM initially, because depending on the CPU model multiple cores may reduce performance or cause instability, and more than 8 GB may freeze the installation at the country selection step. It advises increasing RAM only after installation and cores only after macOS has run reliably for several hours, and says Intel processors offer better macOS compatibility. Treat that as the project's own compatibility statement, not a general rule.

## Networking, shared folders and audio are opt-in

The default container uses bridge networking and shares the host's IP address. For a separate address the README shows a macvlan network created with docker network create -d macvlan, taking a subnet, gateway and IP range; the feature list also mentions NAT, user-mode and macvtap as supported modes. File sharing is a 9p mount rather than a Docker bind mount inside the guest: add a volume such as ./example:/shared to the compose file, then run sudo -S mount_9p shared inside macOS, and the folder appears under Go, Computer in Finder. Audio is off unless AUDIO is set to "Y", after which you enable Audio under Settings, Advanced in the web viewer; the README notes the stream only runs while that option is on. Disk growth is handled through DISK_SIZE, for example "256G", and the README says an existing disk can be resized upward without data loss, but only after running diskutil repairDisk disk2 and diskutil apfs resizeContainer disk3 0 inside macOS. Those two commands are specific to the README's disk numbering and are worth reading twice before you run them.

## Where dockur/macos is the wrong tool

The requirements section rules out a large part of the audience. You need Docker or Podman on a Linux host with KVM, or Docker Desktop or Podman Desktop on Windows 11 with nested virtualization enabled. The README states plainly that Docker Desktop on Linux, macOS and Windows 10 does not currently provide KVM access to containers and is therefore not supported. That eliminates the most obvious use case, running macOS on a Mac through Docker Desktop, and it means a Windows 10 machine cannot host this at all. There are hardware floors as well: an AVX2-capable processor such as Intel Haswell or AMD Zen or newer, at least 4 GB of available RAM and at least 32 GB of free disk space, with the default disk image at 64 GB. The AMD caveats above are a second boundary. And the guest is not a managed service: the README's install flow includes manual steps, and the project does not document rollback, snapshotting or backup of the /storage volume, so the state of your macOS machine lives in files you are responsible for.

## How it differs from a hand-built OSX-KVM setup

The closest alternative is doing this yourself with QEMU and the OSX-KVM scripts, which is where dockur/macos gets its firmware and its pinned OSX-KVM commit. The difference is packaging and operations. A manual setup leaves you to fetch OVMF, build or download an OpenCore image, generate serials with macserial, and wire up a display; the container bakes all of that in, pins the versions in the Dockerfile, and serves the console over HTTP on 8006 instead of a local VNC client. It also adds the VERSION variable, which the README maps to five macOS releases, and the DISK_SIZE, RAM_SIZE, CPU_CORES and AUDIO variables. What you give up is control over the QEMU invocation and visibility into it: if something misbehaves, you are debugging through the project's src scripts rather than your own command line. A cloud Mac instance is the other alternative, and it avoids the KVM and AVX2 requirements entirely at the cost of a monthly bill and a machine you do not own. Between the two, dockur/macos makes sense when the hardware is already sitting in your rack.

## Maintenance, licence and what to check before adopting

The repository is not archived, and its last push was on 2026-09-08, with releases v3.10, v3.11 and v3.12 landing in August 2026. That is a recent cadence, and the Dockerfile shows the maintenance cost clearly: it pins qemux/qemu:7.50, OpenCore 1.0.7, VMHide 2.0.0, LongQT-OpenCore 0.7 and an OSX-KVM commit hash. Upgrading any of those means rebuilding the image, and the OSX-KVM commit pin means firmware updates arrive only when the project bumps that argument. The project's own licence is MIT, which covers the Shell scripts, Dockerfile and assets in this repository. It does not cover macOS, OpenCore, VMHide or QEMU, each of which carries its own terms, and installing macOS on non-Apple hardware raises licensing questions the README does not address. This article cannot give legal advice; read the applicable licences yourself. The upgrade path for users is a new image tag plus a container restart, and the compose file's stop_grace_period of 2m exists because the guest needs time to shut down cleanly.

## Conclusion

Adopt dockur/macos when you have a Linux host with /dev/kvm, an AVX2-capable CPU, 4 GB of RAM to spare and 32 GB of disk, and you want a disposable macOS machine for builds or testing rather than a daily desktop. Skip it on Docker Desktop for Linux, macOS or Windows 10, where the README states containers get no KVM access, and be careful on AMD hosts, where the project warns that multiple cores and more than 8 GB of RAM can freeze installation or destabilise the guest. Before committing, verify that /dev/kvm exists on the host, that your disk can absorb the default 64 GB image, and that you have read the AMD notes on CPU_CORES and RAM_SIZE.

## FAQ

### How do I use dockur/macos?

Start the container and open http://127.0.0.1:8006/ in a browser. After the recovery image downloads you get a progress bar, then the macOS recovery menu, where the README's steps are Disk Utility, erase the largest VirtIO Block Media disk as APFS, close the window, and click Reinstall macOS.

### How do I install macOS on Windows with dockur/macos?

Only Windows 11 with nested virtualization enabled is supported, using Docker Desktop or Podman Desktop. The README states that Docker Desktop on Windows 10 does not provide KVM access to containers and is therefore not supported.

### How do I use macOS recovery in dockur/macos?

The recovery menu appears after the installation files finish downloading in the web viewer. From there the README instructs you to open Disk Utility, erase the VirtIO Block Media disk as APFS, close the window, and click Reinstall macOS.

## Sources

- [dockur/macos on GitHub](https://github.com/dockur/macos)
- [Issues](https://github.com/dockur/macos/issues)
- [License: MIT](https://github.com/dockur/macos/blob/master/LICENSE)
- [README](https://github.com/dockur/macos/blob/master/README.md)
- [Releases](https://github.com/dockur/macos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dockur-macos