macos README

The project's README from github.com/dockur/macos. As one markdown file: README.md.

macOS

Build Version Size Package Pulls

MacOS inside a Docker container.

Features ✨

Usage 🐳

Docker Compose:
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
Docker CLI:
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
Kubernetes:
kubectl apply -f https://raw.githubusercontent.com/dockur/macos/refs/heads/master/kubernetes.yml
GitHub Codespaces:

Open in GitHub Codespaces

Requirements ⚙️

[!NOTE] Docker Desktop on Linux, macOS, and Windows 10 does not currently provide KVM access to containers and is therefore not supported.

FAQ 💬

How do I use it?

Very simple! These are the steps:

Enjoy your brand new machine, and don't forget to star this repo!

How do I select the version of macOS?

By default, macOS 15 (Sequoia) will be installed, but you can add the VERSION environment variable in order to specify an alternative:

environment:
  VERSION: "13"

Select from the values below:

Value Version Name
15 macOS 15 Sequoia
14 macOS 14 Sonoma
13 macOS 13 Ventura
12 macOS 12 Monterey
11 macOS 11 Big Sur

[!NOTE] You can also select macOS 26 (Tahoe), but that is not recommended yet, as it runs very slow for some unknown reason.

How do I change the storage location?

To change the storage location, include the following bind mount in your compose file:

volumes:
  - ./macos:/storage

Replace the example path ./macos with the desired storage folder or named volume.

How do I change the size of the disk?

To expand the default size of 64 GB, add the DISK_SIZE setting to your compose file and set it to your preferred capacity:

environment:
  DISK_SIZE: "256G"

[!TIP] This can also be used to resize an existing disk to a larger capacity without any data loss.

However, afterwards you will need to run the following two commands from the terminal in macOS:

diskutil repairDisk disk2

diskutil apfs resizeContainer disk3 0

to allocate this additional space.

How do I change the amount of CPU or RAM?

By default, macOS will be allowed to use a single CPU core and 4 GB of RAM.

If you want to adjust this, you can specify the desired amount using the following environment variables:

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

[!IMPORTANT]
On AMD systems, avoid assigning multiple CPU cores or more than 8 GB of RAM initially. Depending on the specific AMD CPU model, multiple cores may reduce performance or cause instability, while more than 8 GB of RAM may cause the installation to freeze at the country selection step. Increase the RAM only after installation, and the core count only after macOS has been running reliably for several hours.

Intel processors offer much better macOS compatibility, so multiple cores and more RAM can be assigned from the start without causing these issues.

How do I enable audio?

Audio is disabled by default. To stream it to the browser, add the following environment variable:

environment:
  AUDIO: "Y"

Then enable Audio under Settings → Advanced in the web viewer. The stream is only active while this option is enabled, so it uses no extra bandwidth otherwise.

How do I share files with the host?

To share files with the host, add the following volume to your compose file:

volumes:
  - ./example:/shared

Then start macOS and execute the following command:

sudo -S mount_9p shared

In Finder’s menu bar, click on “Go – Computer” to access this shared folder, it will show the contents of ./example.

How do I assign an individual IP address to the container?

By default, the container uses bridge networking, which shares the IP address with the host.

If you want to assign an individual IP address to the container, you can create a macvlan network as follows:

docker network create -d macvlan \
    --subnet=192.168.0.0/24 \
    --gateway=192.168.0.1 \
    --ip-range=192.168.0.100/28 \
    -o parent=eth0 vlan

Be sure to modify these values to match your local subnet.

Once you have created the network, change your compose file to look as follows:

services:
  macos:
    container_name: macos
    ..<snip>..
    networks:
      vlan:
        ipv4_address: 192.168.0.100

networks:
  vlan:
    external: true

An added benefit of this approach is that you won't have to perform any port mapping anymore, since all ports will be exposed by default.

[!IMPORTANT]
This IP address won't be accessible from the Docker host due to the design of macvlan, which doesn't permit communication between the two. If this is a concern, you need to create a second macvlan as a workaround.

How can macOS acquire an IP address from my router?

After configuring the container for macvlan, it is possible for macOS to become part of your home network by requesting an IP from your router, just like your other devices.

To enable this mode, in which the container and macOS will have separate IP addresses, add the following lines to your compose file:

environment:
  DHCP: "Y"
devices:
  - /dev/vhost-net
device_cgroup_rules:
  - 'c *:* rwm'

How do I pass through a disk?

You can pass through disk devices or partitions directly by adding them to your compose file in this way:

devices:
  - /dev/sdb:/disk1
  - /dev/sdc1:/disk2

Use /disk1 if you want it to become your main drive, and use /disk2 and higher to add them as secondary drives.

How do I pass through a USB device?

To pass through a USB device, first look up its vendor and product IDs via the lsusb command, then add them to your compose file like this:

environment:
  ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"
devices:
  - /dev/bus/usb

How do I enable dynamic memory allocation?

By default, the VM is allocated the full amount of RAM configured via RAM_SIZE for its entire lifetime.

However, you can enable memory ballooning if you want the container to dynamically reclaim unused guest RAM based on host memory pressure.

Are these all available options?

No. For a complete overview of all supported settings, see the environment variables page.

How do I verify that KVM is available?

First, make sure your platform and container runtime meet the requirements listed above.

On a Linux host, install cpu-checker and run:

sudo apt install cpu-checker
sudo kvm-ok

A working configuration should report:

KVM acceleration can be used

You can also verify that the KVM device exists:

ls -l /dev/kvm

If KVM is unavailable, check whether:

If kvm-ok succeeds but the container still reports that KVM is unavailable, you can temporarily add privileged: true to your Compose file to rule out a permission or device-access issue.

How do I run Windows in a container?

You can use dockur/windows for that. It shares many of the same features, and even has completely automatic installation.

How do I run a Linux desktop in a container?

You can use qemus/qemu in that case.

Yes, this project contains only open-source code and does not distribute macOS itself. Neither does it try to circumvent any copyright protection measures.

However, by installing Apple's macOS, you must accept their end-user license agreement, which does not permit installation on non-official hardware. So only run this container on hardware sold by Apple, as any other use will be a violation of their terms and conditions.

Acknowledgements 🙏

Special thanks to seitenca, this project would not exist without her invaluable work.

Stars 🌟

Stargazers

Disclaimer ⚖️

Only run this container on Apple hardware, any other use is not permitted by their EULA. The product names, logos, brands, and other trademarks referred to within this project are the property of their respective trademark holders. This project is not affiliated, sponsored, or endorsed by Apple Inc.

macos (dockur/macos)

Searching Database…

21.7K ·GitHub
Macos
Что это такое?dockur/macos позволяет запустить полноценную виртуальную машину macOS внутри Docker-контейнера, а также даёт веб-просмотрщик, чтобы управлять ею прямо из браузера.
Как это запустить?Запустите контейнер через Docker Compose (или Docker CLI, Kubernetes, GitHub Codespaces) и откройте порт 8006 в браузере; образ восстановления загрузится автоматически, затем с помощью Дисковой утилиты сотрите виртуальный диск в APFS и пройдите обычный установщик macOS.
Какое железо и программы нужны для запуска?Нужны Docker или Podman на Linux-хосте с поддержкой KVM (или Windows 11 с включённой вложенной виртуализацией в Docker Desktop), процессор с поддержкой AVX2, например Intel Haswell или AMD Ryzen серии 1000 и новее, не менее 4 ГБ оперативной памяти и 32 ГБ свободного места на диске.
Законно ли запускать это на любом ПК?Сам проект имеет открытый исходный код и не распространяет macOS, но лицензионное соглашение Apple (EULA) разрешает установку macOS только на оригинальное оборудование Apple, поэтому использование этого контейнера на не-Apple железе нарушает условия Apple.
Можно ли запустить это через Docker Desktop на моём Mac или на компьютере с Windows 10?Нет: Docker Desktop на Linux, macOS и Windows 10 не даёт контейнерам доступа к KVM, поэтому работает только Docker/Podman на нативном Linux-хосте или Windows 11 с включённой вложенной виртуализацией.
Какая версия macOS устанавливается по умолчанию?По умолчанию устанавливается macOS 15 (Sequoia); для более старых версий можно задать переменную VERSION со значением 11-14, либо попробовать 26 (Tahoe), хотя Tahoe сейчас работает очень медленно.
Что будет, если выделить хосту AMD много ядер процессора или много оперативной памяти?На системах AMD назначение нескольких ядер может снизить производительность или привести к нестабильной работе, а при более чем 8 ГБ ОЗУ установщик может зависнуть на экране выбора страны. Процессоры Intel с дополнительными ресурсами справляются заметно лучше с самого начала.
Можно ли обмениваться файлами между хостом и гостевой macOS?Да: смонтируйте папку хоста в контейнер как том, а после запуска macOS откройте её в Finder через меню «Переход» > «Компьютер».
Есть ли похожий проект для запуска Windows или Linux в Docker?Да, dockur/windows использует тот же подход для Windows с полностью автоматической установкой, а для Linux-рабочих столов можно использовать qemus/qemu.
What are similar projects?Docker-OSX, windows, ProxmoxVE, vphone-aio, macOS-Simple-KVM, OSX-KVM, macos-virtualbox, UTM
Which topics is it in?macos-installer, macos-virtual-machine, macos-vm, docker-container, macosx, hypervisor, osx, kvm, vm, usb, remote-desktop, virtual-machine
Creator
dockur
Size
1.7 MB
Stars
21.7K
Updated
CommitSep 28Releasev3.12Aug 21
Age
2y
Commits · 90 Days