Install macOS Big Sur Or Catalina In A Virtual Machine Using Docker-OSX

macOS Big Sur Docker QEMU Ubuntu

Docker-OSX is a project that makes macOS run near native using OSX-KVM inside a Docker container. Using this, you'll be able to install macOS in a QEMU virtual machine (via Docker), and run the macOS Catalina or Big Sur desktop, or boot to the OSX shell.

The Docker-OSX project provides four Docker images:

  • sickcodes/docker-osx:latest - original base recovery image using macOS Catalina
  • sickcodes/docker-osx:big-sur - original base recovery image using macOS Big Sur
  • sickcodes/docker-osx:naked - supply your own .img file (using -v "${PWD}/disk.img:/image")
  • sickcodes/docker-osx:auto - large (~19.4GB) docker image that boots to OSX shell (has SSH enabled, using user as the username and alpine as the password; you need about 50GB of disk space to run this image)

Features include:

  • X11 Forwarding
  • Full auto mode: boot straight to OSX shell and even run commands as runtime arguments
  • Kubernetes Helm Chart. See ./helm
  • SSH on localhost:50922
  • VNC version on localhost:8888 (the VNC version is in a separate directory due to the security risks involved with using VNC)
  • Create an ARMY of the same exact container using docker commit
  • Xfvb headless mode

The project also includes instructions for various tweaks, like forwarding additional ports, changing screen resolution, enable network forwarding, allow USB passthrough, quick start instructions for using the large pre-made image and using your own image, and more (all available on the project's page).

It's worth noting from the start that Apple doesn't allow installing macOS on non-Apple hardware, so to use this legally, your OS must be installed on Apple hardware. Also, to use this, your computer CPU needs to support hardware virtualization; see the KVM checklist from here to find out if your CPU supports it (you can also run sudo kvm-ok which will return "KVM acceleration can be used" if everything is ok).

On my Ubuntu 20.10 desktop, installing macOS using the sickcodes/docker-osx:big-sur image took about 55 minutes. The Docker image takes about 3.2 GB of disk space, while the container space usage for this is around 35 GB.

You may want to also check out Sosumi, a snap package that makes it easy to download and install macOS Catalina in a virtual machine on Linux, which also uses QEMU + KVM, and is based on macOS-Simple-KVM. It's worth noting that Sosumi hasn't been updated since around the time it was first released.

Below you'll find instructions for using Docker (Docker-OSX) to run a macOS (Catalina or Big Sur) base recovery image, install and run macOS (with the option of setting a custom resolution; with no options specified it uses 1920x1080). There are also instructions for removing the container.

You might also like: LazyDocker: Docker And Docker Compose Terminal UI

How to install macOS (OSX) in QEMU + KVM using Docker-OSX

1. Prerequisites.

Before continuing, make sure your computer supports hardware virtualization and that it's enabled in the BIOS (you could check using sudo kvm-ok which will return "KVM acceleration can be used" if everything is ok). Once this is done, you can continue with the rest of the instructions below.

Start by making sure you have Docker installed (also see the official Docker installation documentation). 

Also install QEMU on the host system if you haven't already. You may also need to add your user to the kvm group using sudo usermod -aG kvm $USER for this to work properly.

As for required disk space, read my comment from further up this article for a rough estimation. For sickcodes/docker-osx:auto you'll need about 50 GB of disk space to use it.

2. Start Docker-OSX.

Run macOS Big Sur or Catalina using Docker-OSX (for other options, see the Docker-OSX project page - e.g. you can run it headless, using your own imagerun sickcodes/docker-osx:latest allowing SSH into macOS, etc.; you may also want to check out these custom QEMU arguments that can be used for setting the number of CPU cores, available RAM, etc.):

  • Run the macOS Big Sur (change the WIDTH and HEIGHT values to the screen resolution you want to use for your macOS Big Sur virtual machine; I'm using 1600x900 below) using the base recovery image:

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -e GENERATE_UNIQUE=true \
    -e DEVICE_MODEL="iMacPro1,1" \
    -e WIDTH=1600 \
    -e HEIGHT=900 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \

  • Run macOS Catalina (change the WIDTH and HEIGHT values to the screen resolution you want to use for your macOS Big Sur virtual machine; I'm using 1600x900 below) using the base recovery image:

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -e GENERATE_UNIQUE=true \
    -e DEVICE_MODEL="iMacPro1,1" \
    -e WIDTH=1600 \
    -e HEIGHT=900 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \

This may take a few minutes.

The above Docker run commands use the basic options for launching macOS (basic recovery image, used to install macOS) in QEMU using Docker, provided by the Docker-OSX project page with the addition of options for screen resolution. If you remove the GENERATE_UNIQUE, DEVICE_MODEL, WIDTH and HEIGHT options, the virtual machine will use the default (1920x1080) screen resolution.

3. Use Disk Utility to format the largest QEMU HARDDISK.

After a few minutes, the macOS virtual machine will start. Boot to macOS Base System and choose Disk Utility from the menu:

macOS QEMU Docker disk utility

Next, in the Disk Utility tool, check which is the largest hard disk on the left from the 2 QEMU HARDDISK Media, and click on the largest one (it's 214,75 GB in the version I'm using for testing this).

Tip: to have the QEMU virtual machine release your mouse, press Ctrl + Alt + g (in some cases, that's only Ctrl + g).

Now click the Erase button from the Disk Utility toolbar to format this hard disk:

macOS QEMU Docker disk utility

Set a name for the disk, e.g. "macOS", and leave the other options to their defaults (they are Format: APFS for macOS Big Sur and Mac OS Extended (Journaled) for macOS Catalina, with the Schema being GUID Parition Map for both).

Once you've finished erasing the largest QEMU HDD, close the Disk Utility dialog.

4. Install macOS in the virtual machine.

After closing Disk Utility, you'll once again get to the menu from where you can start Disk Utility, etc. This time though, you'll need to select the option to Reinstall macOS Big Sur (or, if you're using the sickcodes/docker-osx:latest image which has Catalina, this option is called just Reinstall macOS):

macOS QEMU Docker reinstall

Click Continue, then Agree, and you'll get to a screen from where you can choose the HDD you've formatted under step 3 (it shows up using the name you've entered when erasing it, e.g. macOS in our example). Select the HDD and click Continue:

macOS QEMU Docker select disk

The macOS Big Sur / Catalina (depending on which image you chose) installation will now start:

macOS QEMU Docker installing

After a while, the mac OSX virtual machine will restart. Choose the macOS Installer entry on boot:

macOS QEMU Docker installer

Once the installation has finished, this boot entry becomes just "macOS", and allows you to boot into your new macOS installation inside a virtual machine:

macOS QEMU Docker macOS boot menu

Now you'll need to choose your country or region, optionally sign in with your Apple ID, agree to the terms and conditions etc., as well as create your computer account (username and password).

Note that after installing macOS and booting it for the first time, I had to select the macOS entry twice (it rebooted after choosing it for the first time). Also, there's mouse lag (and general lag) through the macOS installation process, but this no longer occurs (or is much less noticeable; this depends on your computer hardware) once you run the installed macOS virtual machine.

5. Start your newly installed macOS virtual machine.

When you want to start your newly installed macOS virtual machine, run docker ps -a to see the container ID and/or name:

docker ps -a

Then start the container:

docker start Container_ID_or_Name

Replace Container_ID_or_Name with the container ID or name obtained using the previous command.

You might also like: Portainer: Web-Based Docker GUI For Remote Or Local Use

How to remove Docker-OSX

So you've decided you want to remove Docker-OSX. Start by running the following command to get a list of Docker container names and IDs:

docker container ls -a

Using this command, identify the container you want to remove. Now stop and remove the container using:

docker container stop ID_or_Image

docker container rm ID_or_Image

Replace ID_or_Image with the container ID or image as obtained using the previous command.

To remove the Docker-OSX image, start by using this command to list existing Docker images:

docker image ls

Next, remove the Docker-OSX image using:

docker image rm Image_ID

Replace Image_ID with the image ID you've got using the previous command.

via (GR)