dockur/macos: Run macOS in a Docker Container with KVM Acceleration

dockur/macos: Run macOS in a Docker Container with KVM Acceleration

Summary

dockur/macos is an innovative GitHub project that enables users to run macOS within a Docker container, leveraging KVM acceleration for optimal performance. This solution simplifies the process of setting up a macOS virtual machine, offering a web-based viewer and automatic download of macOS images. It provides a highly convenient and flexible way to access a macOS environment for various purposes, including development and testing.

Repository Info

Updated on October 12, 2025
View on GitHub

Tags

dockermacosvirtualizationcontainershellosxdevelopmenttesting

Click on any tag to explore related repositories

Introduction

The dockur/macos project offers a unique solution for running macOS directly inside a Docker container. This innovative approach combines the power of containerization with the functionality of a full macOS environment, enhanced by KVM acceleration for near-native performance. It's an ideal tool for developers, testers, or anyone who needs a flexible and isolated macOS instance without dedicated Apple hardware (though the EULA requires running on Apple hardware).

Key features include:

  • KVM acceleration for high performance.
  • A convenient web-based viewer for easy interaction.
  • Automatic download of macOS images, simplifying setup.
  • Support for various macOS versions, including Sonoma, Ventura, and Monterey.

Installation

Getting dockur/macos up and running is straightforward, primarily using Docker Compose or the Docker CLI.

Via Docker Compose

For a persistent and easily configurable setup, Docker Compose is recommended. Create a docker-compose.yaml file with the following content:

services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      VERSION: "14" # Specify macOS version (e.g., "14" for Sonoma)
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006 # Web-based viewer
      - 5900:5900/tcp # VNC access
      - 5900:5900/udp # VNC access
    volumes:
      - ./macos:/storage # Persistent storage for macOS
    restart: always
    stop_grace_period: 2m

Then, simply run:

docker compose up -d

Via Docker CLI

For a quick test or single-run instance, you can use the 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 dockurr/macos

After starting the container, access your macOS instance by navigating to http://127.0.0.1:8006/ in your web browser. Follow the on-screen instructions to install macOS, similar to a physical machine.

Examples

dockur/macos offers extensive customization through environment variables. Here are a few common examples:

Changing macOS Version

You can specify which macOS version to install by setting the VERSION environment variable. For example, to install macOS 13 (Ventura):

environment:
  VERSION: "13" # "15" for Sequoia, "14" for Sonoma, "13" for Ventura, etc.

Adjusting Disk Size

Expand the default 64 GB disk size by adding DISK_SIZE:

environment:
  DISK_SIZE: "256G" # Set to your preferred capacity, e.g., "128G", "512G"

Customizing CPU and RAM

Control the resources allocated to your macOS container:

environment:
  RAM_SIZE: "8G" # Allocate 8 GB of RAM
  CPU_CORES: "4" # Assign 4 CPU cores

For more advanced configurations, such as network setup, USB passthrough, or file sharing, refer to the comprehensive FAQ section in the project's GitHub README.

Why Use dockur/macos?

This project stands out for several reasons:

  • Ease of Use: Simplifies the complex process of virtualizing macOS into a few Docker commands.
  • Performance: KVM acceleration ensures that your macOS instance runs efficiently, providing a smooth user experience.
  • Flexibility: Easily spin up different macOS versions, adjust resources, and manage multiple instances.
  • Isolation: Provides a clean, isolated macOS environment, perfect for development, testing, or running specific macOS-only applications without affecting your host system.
  • Accessibility: Access your macOS VM from any web browser, making it highly convenient.

It's important to note the project's 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."

Links