Guide · Open source

How to use macOS in Docker: setup, versions and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

dockur/macos packages macOS so it runs inside a Docker container on a Linux machine with KVM support. It downloads macOS automatically, installs it with little manual setup, and you use it through a web browser on port 8006. This guide shows you how to start it, complete the installation and adjust the common settings.

macOSdockur/macos · ★ 21.7k · MIT Install options & downloads

Quick start

1Check your host. Confirm you have a Linux host with KVM support, an AVX2-capable processor, at least 4 GB of available RAM and 32 GB of free disk space.
2Start the container. Run the Docker CLI command with VERSION set to the macOS version you want and port 8006 mapped.
3Open the web viewer. Go to http://127.0.0.1:8006/ in your browser and wait while the recovery image and installation files download.
4Format the disk. In the recovery menu, open Disk Utility, select the largest Apple Inc. VirtIO Block Media disk and erase it as APFS.
5Reinstall macOS. Close Disk Utility, click Reinstall macOS, select the formatted disk and follow the setup screens.
6Adjust settings as needed. Use the environment variables for version, RAM, CPU and disk size in your compose file or command.

Check the requirements before you start

You need Docker or Podman on a Linux host with KVM support. The host also needs an AVX2-capable processor, such as Intel Haswell (4th-generation Core) or AMD Zen (Ryzen 1000 series) or newer, at least 4 GB of available RAM and at least 32 GB of free disk space.

Docker Desktop on Linux, macOS, and Windows 10 does not currently provide KVM access to containers and is not supported.
Windows 11 can be used with Docker Desktop or Podman Desktop if nested virtualization is enabled.

Start the macOS container

You can start the container with Docker Compose or the Docker CLI. The Docker CLI command below uses VERSION=14 for macOS 14 Sonoma and maps port 8006 to the host.

Compose users can use the same settings in a services block with the image dockurr/macos, the devices /dev/kvm and /dev/net/tun, the NET_ADMIN capability and the volume ./macos:/storage.

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 docker.io/dockurr/macos

Complete the macOS installation in your browser

Open http://127.0.0.1:8006/ in your web browser after the container starts. The recovery image downloads first, then macOS downloads the remaining installation files behind a black screen with a progress bar. When the macOS recovery menu appears, follow the installer steps.

Choose Disk Utility, then select the largest Apple Inc. VirtIO Block Media disk.
Click Erase, format the disk to APFS and give it any name.
Close the window and click Reinstall macOS, then select the disk you created.
Select your region, language and keyboard settings.
When Migration Assistant asks to transfer data, select Not now.
On the Apple ID screen, select Set Up Later, then Skip.
On the Create a Computer Account screen, enter a username and password, then Continue.

Choose the macOS version

By default, macOS 15 (Sequoia) is installed. Set the VERSION environment variable to install another version. The supported values are 15 (Sequoia), 14 (Sonoma), 13 (Ventura), 12 (Monterey) and 11 (Big Sur).

The README also notes that macOS 26 (Tahoe) can be selected but is not recommended yet because it runs very slowly for some unknown reason.

environment:
  VERSION: "13"

Adjust CPU, RAM, disk size and storage location

By default macOS can use 2 CPU cores and 4 GB of RAM. Set RAM_SIZE and CPU_CORES to change this. The default disk is 64 GB; set DISK_SIZE to make it larger. The storage folder is set with the bind mount ./macos:/storage, and you can replace ./macos with another folder or a named volume.

On AMD systems, do not assign more than 8 GB of RAM during the initial installation.

Setting DISK_SIZE can also resize an existing disk to a larger capacity without data loss, but you then need to run the diskutil commands in macOS shown in the source.

environment:
  RAM_SIZE: "8G"
  CPU_CORES: "4"
  DISK_SIZE: "256G"

To share files with the host, add the volume ./example:/shared, then run sudo -S mount_9p shared inside macOS and open the shared folder from Finder under Go, then Computer.

Audio is off by default. Set AUDIO to Y, then enable Audio under Settings, then Advanced in the web viewer. For a separate IP address, the source describes creating a macvlan network. Note that the macvlan address cannot be reached from the Docker host without a workaround.

volumes:
  - ./example:/shared

What people use it for

Developers testing software on macOS from a Linux machine.
Trying macOS without buying Apple hardware.
Creating a disposable macOS environment that starts and stops with Docker.
Learning the macOS setup process in a safe, separate environment.

Frequently asked questions

How do I install macOS with Docker?

Run the Docker CLI command from this guide on a Linux host with KVM support, or use the equivalent Docker Compose file. Then open http://127.0.0.1:8006/ in your browser and follow the on-screen installation steps.

What are the requirements to run macOS in Docker?

The source lists Docker or Podman on a Linux host with KVM support, an AVX2-capable processor, at least 4 GB of available RAM and at least 32 GB of free disk space. Windows 11 with nested virtualization is also listed as an option.

Can I run macOS Docker on Windows or macOS?

Docker Desktop on Linux, macOS and Windows 10 is stated as not supported because it does not provide KVM access to containers. Windows 11 with Docker Desktop or Podman Desktop and nested virtualization is listed as a supported path.

Which macOS version does it install by default?

It installs macOS 15 (Sequoia) by default. Set the VERSION environment variable to 14, 13, 12 or 11 to install an older supported version.

How do I change the macOS disk size or RAM?

Set DISK_SIZE for disk capacity, RAM_SIZE for memory and CPU_CORES for CPU cores in your environment settings. The defaults are a 64 GB disk, 4 GB of RAM and 2 CPU cores.

Is dockur/macos free to use?

The project is released under the MIT licence. The source does not describe pricing, and it is only described as a way to run macOS in a container, not as a licensed macOS build service.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

dockur/macos suits developers and curious users who run Linux, can enable KVM and are comfortable with Docker and virtualization settings. If you need a production or licensed macOS build service, or your hardware lacks AVX2 or the minimum RAM and disk, pick another option such as QEMU, Quickemu, OSX-KVM or Docker-OSX.

Install options & downloads