Skip to content

Docs: Update README.md to be more concise and accurate #893

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Docs: Update README.md to be more concise and accurate #893

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 31 additions & 101 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,6 @@ If you like this project, consider contributing here or upstream!

## Quick Start Docker-OSX

Video setup tutorial is also available here: https://www.youtube.com/watch?v=wLezYl77Ll8
Copy link

@PhracturedBlue PhracturedBlue Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While the video is antiquated, it describes the process of deleting and recreating the disk image which is necessary before doing install. Woithout linking the video, the README should describe this process I think


**Windows users:** [click here to see the notes below](#id-like-to-run-docker-osx-on-windows)!

<p align="center">
Expand All @@ -56,104 +54,38 @@ First time here? try [initial setup](#initial-setup), otherwise try the instruct

Release names and their version:

### Catalina (10.15) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

```bash
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e SHORTNAME=catalina \
sickcodes/docker-osx:latest

# docker build -t docker-osx .
```
### Big Sur (11) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

```bash
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e SHORTNAME=big-sur \
sickcodes/docker-osx:latest

# docker build -t docker-osx .
```

### Monterey (12) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

```bash

docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e GENERATE_UNIQUE=true \
-e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist' \
-e SHORTNAME=monterey \
sickcodes/docker-osx:latest

# docker build -t docker-osx .
```

### Ventura (13) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

```bash

docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e GENERATE_UNIQUE=true \
-e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist' \
-e SHORTNAME=ventura \
sickcodes/docker-osx:latest

# docker build -t docker-osx .
```
You can run any version of macOS by changing the `SHORTNAME` environment variable.

### Sonoma (14) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)
| macOS Version | `SHORTNAME` |
| --- | --- |
| Sequoia (15) | `sequoia` |
| Sonoma (14) | `sonoma` |
| Ventura (13) | `ventura` |
| Monterey (12) | `monterey` |
| Big Sur (11) | `big-sur` |
| Catalina (10.15) | `catalina` |
| Mojave (10.14) | `mojave` |
| High Sierra (10.13) | `high-sierra` |

```bash

docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e GENERATE_UNIQUE=true \
-e CPU='Haswell-noTSX' \
-e CPUID_FLAGS='kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on' \
-e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom-sonoma.plist' \
-e SHORTNAME=sonoma \
-e "SHORTNAME=sequoia" \
sickcodes/docker-osx:latest

# docker build -t docker-osx .
```

### Sequoia (15) [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest](https://img.shields.io/docker/image-size/sickcodes/docker-osx/latest?label=sickcodes%2Fdocker-osx%3Alatest)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

```bash

docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e GENERATE_UNIQUE=true \
-e CPU='Haswell-noTSX' \
-e CPUID_FLAGS='kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on' \
-e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom-sonoma.plist' \
-e SHORTNAME=sequoia \
sickcodes/docker-osx:latest
**Explanation of the command:**

# docker build -t docker-osx .
```
* `docker run -it`: This command runs a Docker container in interactive mode.
* `--device /dev/kvm`: This flag gives the container access to the KVM for hardware acceleration.
Copy link

@PhracturedBlue PhracturedBlue Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you sure that the GENERATE_UNIQUE=true, and MASTER_PLIST_URL are not needed? I think many users are likley to desire those in an initial setup, and they don't seem to be set in the Dockerfile

* `-p 50922:10022`: This flag maps port `10022` in the container to port `50922` on the host. This is used for SSH access.
* `-v /tmp/.X11-unix:/tmp/.X11-unix`: This flag mounts the X11 socket from the host to the container. This is used for GUI forwarding.
* `-e "DISPLAY=${DISPLAY:-:0.0}"`: This flag sets the `DISPLAY` environment variable in the container. This is also used for GUI forwarding.
* `-e "SHORTNAME=sequoia"`: This flag sets the `SHORTNAME` environment variable in the container. This determines which version of macOS to download and install.
* `sickcodes/docker-osx:latest`: This is the name of the Docker image to use.

<!-- #### Run Catalina Pre-Installed [![https://img.shields.io/docker/image-size/sickcodes/docker-osx/auto?label=sickcodes%2Fdocker-osx%3Aauto](https://img.shields.io/docker/image-size/sickcodes/docker-osx/auto?label=sickcodes%2Fdocker-osx%3Aauto)](https://hub.docker.com/r/sickcodes/docker-osx/tags?page=1&ordering=last_updated)

Expand Down Expand Up @@ -429,16 +361,10 @@ Pick one of these while **building**, irrelevant when using docker pull:

There are currently multiple images, each with different use cases (explained [below](#container-images)):

- High Sierra (10.13)
- Mojave (10.14)
- Catalina (10.15)
- Big Sur (11)
- Monterey (12)
- Ventura (13)
- Sonoma (14)
- Auto (pre-made Catalina)
- Naked (use your own .img)
- Naked-Auto (user your own .img and SSH in)
* `sickcodes/docker-osx:latest`: This is the main image. It allows you to run any version of macOS by setting the `SHORTNAME` environment variable.
* `sickcodes/docker-osx:auto`: This is a pre-installed version of Catalina. It is useful for quickly getting started with Docker-OSX.
Copy link

@PhracturedBlue PhracturedBlue Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, as of 2025-11-24 at least, the docker-osx:auto image seems not to exist

* `sickcodes/docker-osx:naked`: This image allows you to use your own `.img` file. This is useful for CI/CD purposes or for using a custom version of macOS.
* `sickcodes/docker-osx:naked-auto`: This image is similar to the `naked` image, but it also allows you to SSH into the container.

High Sierra:

Expand Down Expand Up @@ -962,11 +888,15 @@ Additionally, you can string multiple statements together, for example:
-p 10043:10043 \
```

### Bridged networking
### Networking issues

If you are having trouble connecting to the internet from within the container, you can try the following:

You might not need to do anything with the default setup to enable internet connectivity from inside the container. Additionally, `curl` may work even if `ping` doesn't.
* **Check your firewall settings.** Make sure that your firewall is not blocking the Docker container from accessing the internet.
* **Use a different networking mode.** You can try using a different networking mode, such as `host` or `bridge`.
* **Enable IPv4 forwarding.** If you are using a bridged network, you may need to enable IPv4 forwarding on your host machine.

See discussion [here](https://github.com/sickcodes/Docker-OSX/issues/177) and [here](https://github.com/sickcodes/Docker-OSX/issues/72) and [here](https://github.com/sickcodes/Docker-OSX/issues/88).
See also: [here](https://github.com/sickcodes/Docker-OSX/issues/177), [here](https://github.com/sickcodes/Docker-OSX/issues/72), and [here](https://github.com/sickcodes/Docker-OSX/issues/88).

### Enable IPv4 forwarding for bridged network connections for remote installations

Expand Down