OpenCore-ISO: a preconfigured OpenCore boot image for macOS guests on Proxmox

What the image is and what it deliberately is not

This is a carefully crafted OpenCore ISO image for running macOS virtual machines on Proxmox VE and QEMU and KVM. The description of the build is the part worth knowing, because it tells you what kind of configuration you are getting: built from scratch with a clean, efficient architecture, no legacy configurations, no OVMF patches, no kernel patches, true vanilla macOS. That last clause is the one that will matter most to anyone who has tried this before. The usual route to running macOS under KVM involves a patched kernel that hides non-Apple hardware, and this project exists to avoid that: the guest sees an ordinary configuration and the work is pushed into the OpenCore layer and the QEMU CPU model settings instead. The stated support range runs from Mac OS X 10.4 Tiger through macOS 26 Tahoe, which is an unusually wide span for a macOS virtualisation image.

The download and the one setting people get wrong

The latest image is published as a release asset, LongQT-OpenCore-v0.7.iso, and the macOS installers and recovery images come from a separate repository, macos-iso-builder, which the README names as the only supported source. There is then an important warning and an important tip. The ISOs are true CD/DVD ISO images, and you add them to the virtual machine as a CD/DVD drive, and you must not change media=cdrom to media=disk in the VM configuration. Separately, a script named Create_macOS_ISO.command is provided to run inside the virtual machine so it can download the full macOS installer from Apple and generate a proper DVD-format installer ISO. The repository root also holds Create_Recovery_ISO.command, Mount_EFI.command, Make_ISO.command, Install_Python3.command and Disable_GateKeeper.command, which together describe how the image and its contents are assembled.

Proxmox settings, step by step

The quick start guide walks the Proxmox web interface in order. You create a new VM, give it any available ID and any name, and select the OpenCore ISO as the ISO image while leaving the guest OS type at its default of Linux, which is a detail that surprises people. The machine type is q35 and the BIOS is OVMF with UEFI, the EFI disk is enabled, and Secure Boot is disabled by unticking Pre-Enroll Keys. The QEMU guest agent is enabled for macOS 10.14 through macOS 26 and left disabled for the older releases from 10.4 to 10.13. Memory needs a minimum of 2 GB with 4 GB or more recommended, and the ballooning device is disabled. Finally you add an additional CD/DVD drive for the macOS installer or recovery image and start the machine.

The disk bus depends on the macOS version

The hard disk bus type is not a free choice, and the README gives a table that says so. VirtIO offers better performance, while SATA supports TRIM and Discard for more efficient storage use. The table then maps the versions: macOS 10.15 through macOS 26 supports SATA and VirtIO Block, while macOS 10.4 through macOS 10.14 supports SATA only. There is also a tip about using SATA with SSD emulation and Discard enabled, which automatically turns on TRIM so there is no need to run trimforce enable. That last workaround is a clue about what the configuration is compensating for: VirtIO Block presents a block device that macOS cannot fully interrogate, so Discard has to be emulated at the SATA layer instead.

CPU model is the setting that breaks boots

The CPU section carries a caution that incorrect CPU configuration will cause boot failure, and the guidance is version-dependent. For macOS 10.11 through macOS 26 the recommended type is Skylake-Client-v4 or Skylake-Server-v4, which have AVX-512, while for macOS 10.4 through 10.10 the recommendation is Nehalem. Cores are chosen as a power of two, 1, 2, 4, 8, 16, 32 or 64, and for counts that are not powers of two the guide suggests multiple sockets with a table of worked examples, such as 6 cores as 2 cores across 3 sockets, or 24 cores as 8 across 3. On AMD processors, macOS 10.4 through 12 needs the Advanced option with pcid and spec-ctrl turned off, while macOS 13 through 26 needs the CPU set manually from the Proxmox shell.

qm set [VMID] --args "-cpu Skylake-Client-v4,vendor=GenuineIntel"

Intel hosts have their own adjustments, including overriding the CPUID model on certain Xeon generations and the stepping on Haswell desktops, and the guide recommends avoiding host passthrough CPU types, which it says can be around 30 percent slower on single-core and 44 percent slower on multi-core than the recommended types.

Network adapter choices and the AMD caveat

The network adapter is also version-dependent, and the table is explicit. macOS 11 through 26 uses VirtIO as the default, macOS 10.11 through 10.15 uses VMware vmxnet3, and macOS 10.4 through 10.10 uses Intel E1000. The AMD notes sit inside the CPU section because they interact with it, and there is a footnote pointing at the Dortania buyer guide for the CPU limitations. The README's own tip is worth repeating because it is the reason to prefer this approach over other virtualisation routes: this is likely the best way to run macOS on AMD hardware while retaining full hypervisor access for other virtual machines, and it also overcomes a lot of the AMD CPU limitations listed in that guide. Retaining the hypervisor is the differentiator, since on AMD the usual workaround is to give up nested virtualisation for everything else on the host.

Troubleshooting and the legacy keyboard problem

The troubleshooting list is a short checklist of the four things most often wrong. Secure Boot must be disabled, which means Pre-Enroll Keys is unchecked. The ISO must be mounted as a CD/DVD rather than as a disk. You should try a different CPU model. And for Mac OS X 10.4 Tiger specifically, the machine type should be q35 with a version of 10.0 or older. There is also a separate note about a legacy OS X no-keyboard issue, with two workarounds: add -device usb-kbd to the QEMU arguments, or run device_add usb-kbd in the VM Monitor. The keyboard issue is a good illustration of why the older releases need their own settings, since the input stack in Tiger predates the USB handling that later releases expect.

Where OpenCore-ISO is the wrong choice

Four limits apply. It is a Linux-host tool for running macOS, so it does nothing for you on Apple hardware and nothing for a Windows or Linux guest. It depends on a separate repository for the macOS installers and recovery images, which the README names as the only supported source, so a second project is part of the dependency and that one has to be trusted too. The image encodes a specific configuration, and the CPU and adapter tables show how much of the setup still has to be matched to the macOS release you want, so it saves you the derivation rather than the decisions. And the licensing question sits outside the repository: the code is MIT with a separate OpenCore licence file, but running macOS in a virtual machine on non-Apple hardware is a question about Apple's terms that this project cannot answer for you.

Editorial conclusion

Use OpenCore-ISO when you want to run macOS as a virtual machine on Proxmox or QEMU and do not want to derive the OpenCore configuration yourself, because the image encodes the settings that vary by macOS release and CPU model. Do not treat it as a licence to run macOS without a licence, and check that the terms cover your situation before you deploy it. Verify first which CPU model your macOS version needs, since the guide gives different recommendations for different releases and getting it wrong causes a boot failure, that you attach the image as a CD/DVD drive rather than as a disk, since the README is emphatic that changing media=cdrom to media=disk breaks it, and that Secure Boot is disabled through the Pre-Enroll Keys setting.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. LongQT-sea/OpenCore-ISO on GitHub
4. README
5. Releases