macOS on Incus guide

This guide details the necessary steps to get macOS up and running on Incus, through the macOS on Incus project.

macOS on Incus intends to provide a minimalistic (as in no unnecessary bits) way to run macOS on an as-vanilla-as-possible installation of Incus. It strives to stay as compliant as possible with regulations and license agreements, by not directly distributing any non-free IP, and only providing free software.

Hardware requirements

Unlike Linux virtualization, macOS virtualization requires a specific hardware configuration to run properly on x86. While this guide provides no support for non-Intel processors, contributions for AMD processors are welcome as long as they respect the project’s minimalistic spirit.

Pursuant to the software license agreement for macOS, you are only allowed to run macOS on an Apple-branded computer, and on it, to run up to two additional instances of macOS. Make sure you fully understand the implications of not complying with these conditions, should you decide not to.

You can easily recognize such hardware by the famous Apple logo. For reference, here is a genuine (at least the sticker is) Apple ProLiant DL360 Gen10 Plus:

Note that this guide also works for other machines, such as the Apple PowerEdge R730, on which it also has been tested.

Should your CPU not be working properly with the macOS on Incus project, feel free to open an issue on GitHub, but keep in mind that most of the investigation will have to be done by you.

Building the installation ISO

macOS on Incus only intends to build installation media using recoveryOS, a special OS responsible for downloading the actual installation images for macOS. This is done because downloading said installation images is notoriously hard. If you can cleanly and reproducibly integrate a tool to download them, don’t hesitate to open an issue on GitHub for us to discuss your work.

For now, macOS on Incus is a source-only distribution. This means that all the tools developed and used in the project have to be compiled. We provide a dedicated tool, Orchard, to perform all the necessary actions.

Orchard has only been tested on Debian 13 and relies on the apt package manager. If you can cleanly and reproducibly run Orchard on another distribution, don’t hesitate to open an issue on GitHub for us to discuss your work. Issues asking to support new distributions will be closed without comment.

Using Orchard

First, clone Orchard with Git and go to its directory:

git clone https://github.com/macOS-on-Incus/orchard
cd orchard

Prepare the development environment with the init action.

./orchard init

You can then build all the necessary files with the build action:

./orchard build

To be able to sign the EFI binaries, Orchard expects sb.cer, sb.crt and sb.key to be present at its root. If you don’t have these at hand, you can simply generate them:

./orchard genkeys

Finally, to package an installation ISO, you just have to use the package action. You can pass an optional --sign to sign the binaries, and an optional version string to download the corresponding macOS version (refer to OpenCore for the accepted versions). If no version is given, the default one suggested by OpenCore will be downloaded, except if a com.apple.recovery.boot directory is present at the root of Orchard, in which case its files will be used.

./orchard package --sign 15.6

This produces a macOS.iso file, which you can then import into incus.

Configuring Incus

The macOS on Incus project can run on any recent Incus installation, although we recommend always using the latest stable release, as new features will bring enhanced support, which this guide will later assume as it gets updated.

For macOS to work on Incus, a QEMU scriptlet is required to perform all kinds of low-level operations. For more details, you can have a look at the Technical details section.

Given a profile macos, the QEMU scriptlet can be set this way:

curl https://raw.githubusercontent.com/macOS-on-Incus/QEMU-Scriptlet/refs/heads/main/scriptlet.py | incus profile set macos raw.qemu.scriptlet=-

Note that this scriptlet can change as new versions of Incus get released; we therefore recommend you to watch the related GitHub repository for updates.

The same operation can be done on any singular instance, should you prefer not to use a profile.

If your system has AppArmor running, you will want to add the following configuraton key (don’t forget the trailing comma):

raw.apparmor: /dev/zero k,

SecureBoot

On a modern installation that supports it, the SecureBoot DB certificate generated by Orchard, sb.crt, can be imported in your profile (here, macos) with:

incus profile set macos initial.secureboot.db=- < sb.crt

The same operation can be done on any singular instance, provided it has not yet been started (otherwise, you will have to reset its NVRAM with incus low-level repair rebuild-nvram).

Should you be running a version of Incus that does not support SecureBoot key management, Orchard stores an X.509 version of the certificate in the generated ISO, at \EFI\sb.cer. A visual step-by-step guide to import it in the EFI setup menu is provided here.

Installation

After Incus has been configured and the installation ISO has been imported, you can proceed to the actual OS installation. Do not forget to set image.os: macOS on your instance, or it just won’t boot. This is needed as Incus performs special tuning depending on the OS it virtualizes.

Recovery installation

You should be welcomed by a gray Apple logo on a white background with a progress bar, then, after a good minute, a white apple on a black background, then the installer’s language selection screen:

You should then format your hard drive in APFS. Choose the name you want for your disk, but please don’t write config or incus_agent, as that is going to turn out very badly for you. macOS is a good name:

Then, proceed with the installation:

Do not be impatient; it is not unusual for this step to take a good hour, even on a beefy system.

macOS configuration

Your VM should reboot about four times (once with a black background, once with a white blackground, once with a white then a black background, and finally once with a white background, then the macOS welcome screen). Proceed with your system configuration, and do not forget not to agree to send information to Apple. Now would be a pretty bad moment to enter your Apple ID, should you have one.

Last steps

Agent installation

As mentioned on the official documentation, to install the agent, you have to do, as root:

mount_9p config
cd /Volumes/config
./install.sh

Do not forget to give sh full disk access (System Settings > Privacy & Security > Full Disk Access > + > /bin/sh):

Text console

If you want to enable a text console for your macOS instance, you have to download an additional tool. When first opening it, macOS will prevent you from running it, as it is very dangerous to open a stranger’s installation package. If you trust this stranger, you can tell macOS in System Settings > Privacy & Security > Open Anyway:

Technical details

QEMU scriptlet

macOS is not a general-purpose OS. It has been made to work on a limited set of hardware configurations, and these configurations have something in common: they do not support hot-plugging PCI devices, or even enumerating hot-plugged devices. Incus relies a lot on PCI hotplug, so we need to remap devices created by Incus before starting macOS. This is what our QEMU scriptlet does: disks are remapped to SATA drives, network cards are remapped to USB Ethernet adapters, and a lot of other useful devices are remapped to somewhere macOS can find them. This forum post gives the whole context that led to this project.

Bootloader dance

macOS on Incus stands on the shoulder of giants. This project couldn’t exist without the incredible and dedicated work from the Acidanthera and Dortania teams. macOS on Incus automates the interaction with the OpenCore bootloader in several ways.

On the first boot, our bootloader sideloads OpenCore with a special configuration (called the Stage-1 configuration) that tells it to load the recovery image located within the installation ISO built by Orchard. On the first reboot of the installer (and any subsequent boot if the installation drive is still there), our bootloader copies another configuration (the Stage-2 configuration) to the newly-created EFI partition, then sideloads a simple tool that ejects the installation drive, then sideloads OpenCore with the Stage-2 configuration. This little dance allows a hands-free (well, except for the interactive parts) installation of macOS on Incus, and it is, to the best of our knowledge, the only tool that automates these steps of the macOS installation process on virtualized environments.

7 Likes

can you create a snapshot of the vm, then use the snapshot to cteate a new macOS vm?

Of course! Even with the dark magic we apply to the configuration of macOS instances, they are still Incus VMs.

@stgraber, could you move it to the Tutorials category? It looks like I’m unable to do it myself.

2 Likes

This looks awesome. I’ve got an existing OSX virtual machine that I spun up years ago following the instructions here GitHub - kholia/OSX-KVM: Run macOS on QEMU/KVM. With OpenCore + Monterey + Ventura + Sonoma support now! Only commercial (paid) support is available now to avoid spammy issues. No Mac system is required. · GitHub. I’m trying to intuit my way to move that existing structure over so that it can be managed by incus instead of a direct qemu-kvm script. Was wondering if anybody else had done that or otherwise might have suggestions that would ease the process for someone whose technical knowledge falls far short of understanding everything that is going on in this guide (or even the guide that I followed to create my current setup).

I’d highly advise you to wait a bit for Incus 7.4 to be released, as there are a few features that will greatly simplify the whole thing (and that will require me to patch the guide). And I also have to check if we haven’t done anything over the past year that may have completely broken the guide. So if you’re not in a hurry, please wait a few weeks to give me time for all of that.

1 Like

But also, the guide is technical on purpose. Running macOS on x86 is not at all plug and play, and I can’t do tech support for someone with a CPU that I don’t have. You probably have to tweak the NVRAM a fair bit before the OS even boots up, and the best place to get support is not here unfortunately. I’m not saying that to gate-keep any kind of arcane knowledge or whatever, but I don’t want to give false hopes; this is something for very patient people that are willing to read dozens and dozens of manual pages related to OpenCore.

Thanks for the amazingly prompt response! Given that I’ve had this in place for at least a couple of years now, a few more weeks is certainly not an issue.

And as you are probably aware, macOS 27 (due out very soon) will drop Intel capability entirely, and at that point macOS 26 will have only two years support left. So enjoy it while you can :slight_smile:

Yeah, it was fun while it lasted. But it was more of a nice pretext for me to get familiar with Incus internals than anything else, really :slight_smile:

1 Like

Hi,
I just updated the guide here and on GitHub, and patched the QEMU scriptlet, as the project wasn’t running anymore on Incus 7.x. I’ve upgraded my testing environment and can confirm it is working well (and the installation is even a bit easier on the latest Incus versions).

Hello,

I’ve been trying to setup a macos vm on incus 7.5.1, however it doesn’t seem to want to boot up. I signed the images and imported the secure boot cert, but starting the VM reports this:

Error: Failed running QEMU scriptlet at pre-start stage: Failed to run: GenericError: Failed to find file descriptor with matching flags=0x2

qemu.log:

qemu-system-x86_64:/run/incus/ghrunner-macos/qemu.conf:275: warning: Spice: (../server/reds.cpp:322):void reds_register_channel(RedsState*, RedChannel*): runtime check failed: (reds_find_channel(reds, this_type, this_id) == nullptr)
qemu-system-x86_64:/run/incus/ghrunner-macos/qemu.conf:275: warning: Spice: (../server/reds.cpp:322):void reds_register_channel(RedsState*, RedChannel*): runtime check failed: (reds_find_channel(reds, this_type, this_id) == nullptr)

Any idea on what could be the cause?

Yeah, that usually suggests a mismatch between caching modes that the scriptlet tries to reproduce and those set by Incus. Just to be sure, are you using the latest version of the scriptlet, and not the previous one (which no longer works with Incus 7.x)?
If this is the case, you can insert log_warn('=====>', inserted) in the remap_storage function, run incus monitor in parallel, then start your instance. Find the block starting with =====> in the incus monitor output and post it here; this may give me more insight on what’s going on.

If the scriptlet is still located at

https://raw.githubusercontent.com/macOS-on-Incus/QEMU-Scriptlet/refs/heads/main/scriptlet.py

, then yes, I recently fetched it so it must be the latest version.

Here is the logged output you asked for:

QEMU scriptlet (pre-start): =====>{"active": True, "backing_file_depth":
    0.0, "bps": 0.0, "bps_rd": 0.0, "bps_wr": 0.0, "cache": {"direct": False, "no-flush":
    False, "writeback": True}, "children": [{"child": "data-file", "node-name": "#block611"},
    {"child": "file", "node-name": "#block516"}], "detect_zeroes": "off", "drv": "qcow2",
    "encrypted": False, "file": "/dev/fdset/0", "image": {"actual-size": 1.511424e+06,
    "cluster-size": 65536.0, "dirty-flag": False, "filename": "/dev/fdset/0", "format":
    "qcow2", "format-specific": {"data": {"compat": "1.1", "compression-type": "zlib",
    "corrupt": False, "data-file": "/var/lib/incus/virtual-machines/ghrunner-macos/image_metadata/root.raw.tmp",
    "data-file-raw": True, "extended-l2": False, "lazy-refcounts": False, "refcount-bits":
    16.0}, "type": "qcow2"}, "limits": {"discard-alignment": 65536.0, "max-iov": 1024.0,
    "min-mem-alignment": 4096.0, "opt-mem-alignment": 4096.0, "request-alignment":
    1.0, "write-zeroes-alignment": 65536.0}, "virtual-size": 1.073741824e+10}, "iops":
    0.0, "iops_rd": 0.0, "iops_wr": 0.0, "node-name": "incus_root", "ro": False, "write_threshold":
    0.0}

Alright, nothing striking me as out of the ordinary. Could you share the qemu.qmp.log file for that instance? That’ll show precisely what parameters Incus is setting on the block devices.

Sure, here is it: https://pastebin.com/raw/MUTphMw7

Ok, rather unexpected. This is not a satisfying solution to me, but you can try setting 'direct': True (instead of False) in the two occurrences after elif driver == 'qcow2':. This should work. I’ll have a look next month to make it more robust…

That makes me curious: which storage driver do you use for your root disk?

after updating the scriptlet, I’m getting another error :confused:

Error: Failed running QEMU scriptlet at pre-start stage: Failed to run: GenericError: 'host_device' driver requires '/dev/fdset/1' to be either a character or block device

here is the new qemu.qmp.log if you need it: https://pastebin.com/raw/iQXS45Yt

I’m using the ahci driver for the sata drive the host is running on

I meant what Incus storage driver. As per your current error, I don’t have more ideas, so I’ll need to reproduce an environment similar to yours (hence the need to know more about your Incus configuration).