Somewhere in nearly every Proxmox homelab forum, the same question shows up: can you run macOS in a VM on this thing? The short answer is yes, sort of, with an asterisk the size of a small planet. The longer answer is what this guide is actually about.

Proxmox VE doesn't list macOS as a supported guest operating system anywhere in its documentation, and Apple doesn't sell macOS as something you install on non-Apple hardware. And yet thousands of developers, testers, and iOS build pipelines run exactly this setup. Both things are true at once, and understanding why is the difference between a working VM and three wasted evenings staring at a gray Apple logo that never progresses.

This guide walks through what actually happens under the hood when macOS boots inside KVM, what you need before you start, the real steps involved, and the errors you're statistically most likely to hit along the way.

What You Will Learn

  • Why macOS isn't officially supported on Proxmox VE, and what makes it boot anyway
  • What Apple's software license actually says about this, in plain terms
  • The hardware and VM settings macOS needs that a normal Linux or Windows VM doesn't
  • A realistic step-by-step process for getting a macOS VM installed and booting
  • The specific errors and kernel panics you're likely to run into, and what causes them

What Is This Feature?

Proxmox VE runs virtual machines using KVM, the Linux kernel's built-in virtualization module, paired with QEMU to emulate the rest of the hardware a guest OS expects to see: a motherboard, a graphics card, USB controllers, and so on. For Linux and Windows guests, this is a well-worn path — Proxmox ships sensible defaults and Microsoft and most Linux distributions test against QEMU directly.

macOS is different because Apple builds it to run only on Apple's own hardware. The installer checks for specific hardware signatures — an Apple SMC (System Management Controller) chip, particular ACPI tables, a board ID that matches a real Mac model — before it will proceed. A stock QEMU VM doesn't have any of that, so the installer refuses to run.

The workaround is a piece of software called OpenCore, originally built for the Hackintosh community (people running macOS on custom-built PCs). OpenCore sits between the VM's firmware and macOS, and it patches the boot process to inject the SMC emulation, fake board identifiers, and ACPI tweaks macOS expects, using virtual hardware that's already close enough to the real thing. QEMU's -device isa-applesmc option provides the SMC emulation on the Proxmox side; OpenCore handles the rest once macOS starts booting.

None of this is built into Proxmox. It's assembled from three separate open-source projects — QEMU's existing Apple SMC support, the OpenCore bootloader, and community scripts (most people use the OSX-KVM project on GitHub) that automate downloading the installer and building the OpenCore boot disk. Proxmox is just the hypervisor hosting the VM; it has no special macOS mode to turn on.

Why Would You Use It?

The most common reason is iOS and macOS app development. Xcode only runs on macOS, and if your day job involves building an iPhone app, you need a Mac somewhere in the loop. A macOS VM on a Proxmox box you already own is a lot cheaper than a dedicated Mac mini sitting idle most of the day.

QA teams use it to test cross-platform software on macOS without buying a physical machine per tester. Some homelab users just want to run Mac-only utilities occasionally, or they're curious what the fuss is about. I'll be honest — if your only goal is "a desktop that feels like macOS," it's not a great use of a weekend. Performance is noticeably below a real Mac, GPU acceleration is limited without passthrough, and you'll spend real time fighting boot issues most other guest OSes don't have. If you have a specific, recurring need for macOS — building an app, running a specific tool — it earns its keep. If you're doing it for novelty, know what you're signing up for first.

Prerequisites

  • A Proxmox VE 8.x or 9.x host with an Intel or AMD CPU — Intel CPUs tend to have fewer quirks since macOS itself is built around Intel-era hardware assumptions, but AMD works with extra CPU flags
  • VT-x (Intel) or AMD-V enabled in the BIOS, plus VT-d/AMD-Vi if you plan to pass through a GPU later
  • At least 4 CPU cores and 8 GB of RAM dedicated to the VM — macOS is not light, and anything less produces a genuinely unpleasant experience
  • 60 GB or more of free storage for the virtual disk; recent macOS installations alone take up 15–20 GB before you've installed a single app
  • A stable internet connection on the Proxmox host, since the installer image gets pulled directly from Apple's own servers
  • Comfort with the Linux command line — this isn't a point-and-click process

You don't need a Mac to follow this guide. You do need patience — budget an evening, not twenty minutes, especially the first time.

Step-by-Step Tutorial

Step 1: Confirm your CPU actually supports virtualization

SSH into your Proxmox host and run:

lscpu | grep Virtualization

You want to see VT-x or AMD-V listed. If nothing shows up, the extension is either missing or turned off in your BIOS — fix that before going any further, since nothing past this point will work without it.

Step 2: Create the VM shell with the right machine type and firmware

macOS needs UEFI firmware, not the older SeaBIOS that Proxmox uses by default for a lot of Linux VMs, and it needs the Q35 chipset emulation rather than the older i440fx one. Create the VM with:

qm create 900 --name macos-vm --memory 8192 --cores 4 --cpu host --machine q35 --bios ovmf --net0 vmxnet3,bridge=vmbr0

Here, 900 is the VMID — pick any unused number in your environment. The --bios ovmf flag switches to UEFI, and --machine q35 gives macOS the newer chipset it expects. Skip either one and the installer typically won't even start.

Add an EFI disk, which stores the UEFI variables the VM needs to remember between reboots:

qm set 900 --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=0

pre-enrolled-keys=0 matters here — Secure Boot's default Microsoft keys will block OpenCore from loading, so this disables that pre-enrollment.

Step 3: Build the OpenCore boot disk

This is the part that isn't a native Proxmox command. On the Proxmox host (or any Linux machine), clone the OSX-KVM project, which packages the fetch script and a ready-made OpenCore configuration:

git clone https://github.com/kholia/OSX-KVM.git
cd OSX-KVM
python3 fetch-macOS.py

The fetch script talks directly to Apple's own software update servers and lets you pick a macOS version to download — it's the same recovery image Apple serves to real Macs, not a modified or pirated copy. It downloads as a BaseSystem.dmg file, which the project's included scripts convert into a raw disk image Proxmox can attach as a virtual drive.

The repository also ships a prebuilt OpenCore.qcow2 image containing the OpenCore bootloader, already configured with the SMC and ACPI patches macOS needs. Copy both the converted installer image and OpenCore.qcow2 to your Proxmox host's storage (commonly /var/lib/vz/images/900/ for VMID 900), then attach them:

qm set 900 --sata0 /var/lib/vz/images/900/OpenCore.qcow2
qm set 900 --sata1 /var/lib/vz/images/900/BaseSystem.img
qm set 900 --sata2 local-lvm:120,format=raw
qm set 900 --boot order=sata0

The third line creates the actual 120 GB disk macOS will install onto. The boot order line tells Proxmox to boot from OpenCore first — it's the bootloader, and it's what presents you with a menu to launch the macOS installer from the recovery image.

Step 4: Add the CPU and SMC arguments

macOS checks the CPU's reported vendor string and a handful of feature flags before it'll boot. Proxmox's GUI doesn't expose these directly, so they go in through the VM's raw QEMU arguments:

qm set 900 --args "-device isa-applesmc,osk='ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc' -smbios type=2 -cpu Penryn,vendor=GenuineIntel,+invtsc,+hypervisor,+kvm_pv_unhalt,+kvm_pv_eoi"

That long quoted string after osk= is the SMC key macOS's kernel expects to see — it's been publicly documented since the earliest Hackintosh SMC emulators and is identical in essentially every macOS-on-QEMU guide, not something specific to your install. The Penryn CPU model tells QEMU to present an older, broadly-compatible Intel CPU signature that macOS's kernel recognizes, rather than exposing your real (and probably much newer) CPU model directly.

Step 5: Boot, install, boot again

Start the VM (qm start 900) and open its console from the Proxmox web UI. You'll land in OpenCore's boot picker — select the macOS installer entry. From there it's Disk Utility first: erase the 120 GB disk you created and format it as APFS, then quit Disk Utility and run the actual installer against that freshly formatted disk.

The installer reboots the VM at least once, sometimes twice, during the process. Each time, go back into OpenCore's boot picker and select the macOS entry (now pointing at your internal disk, not the recovery image) to continue. This is normal — it trips people up the first time because it looks like the installer failed and restarted from scratch, when it's actually just resuming.

Commands Explained

  • qm create — Proxmox's command-line tool for defining a new VM's core hardware: CPU count, RAM, network interface, and so on, before you've installed anything.
  • --bios ovmf — switches the VM's firmware from SeaBIOS to OVMF, an open-source UEFI implementation. macOS requires UEFI; it has no BIOS-era boot path.
  • --efidisk0 — allocates a small dedicated disk to store UEFI variables (like Secure Boot state) that need to persist across reboots, separate from your main OS disk.
  • qm set --args — passes raw, low-level flags straight through to the underlying QEMU process, bypassing anything Proxmox's own GUI or CLI options expose. It's the escape hatch for hardware quirks Proxmox wasn't designed around, which is exactly the category macOS falls into.
  • -cpu Penryn,vendor=GenuineIntel,... — tells QEMU which virtual CPU model and feature flags to present to the guest. macOS's kernel checks these at boot and panics on models or vendor strings it doesn't recognize as genuinely Intel.

Common Errors

Stuck at a gray Apple logo with no progress bar. Usually means the SMC or CPU arguments from Step 4 are missing or malformed — double-check the --args string for typos, especially in the quoted OSK key.

"This version of Mac OS X is not supported on this platform" during install. This is the installer detecting a CPU it doesn't recognize, almost always because the -cpu Penryn flag (or an equivalent supported model) wasn't applied correctly.

Kernel panic mentioning "invalid slide value." A known ASLR-related boot quirk on certain OpenCore/macOS version combinations. It's fixed inside OpenCore's own configuration file, not on the Proxmox side, by adjusting the kernel slide setting.

VM boots but never reaches OpenCore's picker at all. Check that --boot order=sata0 actually points at the disk holding OpenCore.qcow2, and that Secure Boot's pre-enrolled keys are disabled as shown in Step 2 — enrolled Microsoft keys will silently block OpenCore from loading.

Troubleshooting

If the installer boots but crashes with a panic referencing CPU topology or core count, check how many vCPUs you assigned. macOS's kernel expects core and thread counts that match a real Mac's topology — odd numbers like 3 or 5 cores are a common trigger. Stick to even numbers, and 4 or 6 cores is a safe, well-tested starting point.

Sound and networking usually work out of the box through OpenCore's built-in kext support, but graphics acceleration doesn't — without a passed-through GPU, you're limited to a basic framebuffer with no hardware acceleration. That's fine for command-line development work and most testing, but it's not going to run anything graphically demanding.

If performance feels sluggish even for basic tasks, check that --cpu host is actually applied at the VM level (separate from the Penryn override inside the args string, which only affects how macOS identifies the CPU, not the underlying performance) and that you haven't accidentally left the VM's balloon device enabled — macOS handles memory ballooning poorly and it's worth disabling for this guest specifically.

Best Practices

Snapshot the VM immediately after a clean, working install, before you update anything or install software. macOS updates inside a VM are one of the more fragile parts of this whole setup, and a snapshot means a broken update costs you five minutes instead of a full reinstall.

Keep the VM's disk on fast local storage — NVMe or a decent SSD-backed local-lvm — rather than a network share. macOS is sensitive to I/O latency during boot in a way that shows up as long hangs on spinning rust or slow NFS-backed storage.

Match your macOS version to your OpenCore build deliberately rather than always grabbing the newest release of both. OpenCore compatibility with brand-new macOS versions sometimes lags by a few weeks after Apple ships an update, and jumping straight to day-one releases of either piece is where most avoidable breakage happens.

Frequently Asked Questions

Is this legal?
Apple's macOS Software License Agreement restricts installing and running macOS to Apple-branded hardware. Running it in a VM on non-Apple hardware falls outside those terms, regardless of whether you own a genuine macOS license. This is a gray area many developers and hobbyists operate in, but it's not something Apple has authorized, and you should weigh that before relying on it for anything business-critical.

Does Proxmox officially support macOS as a guest?
No. It isn't listed in Proxmox's supported guest OS documentation, and Proxmox support channels won't troubleshoot macOS-specific boot issues. Everything covered here comes from community tooling, not Proxmox itself.

Can I pass through a real GPU for better graphics performance?
Yes, with the same PCI passthrough approach used for Windows or Linux VMs, though macOS's driver support is limited mostly to older AMD GPUs — recent NVIDIA cards generally don't have working macOS drivers at all.

Will the QEMU guest agent work for shutdown and monitoring?
Not the standard one Proxmox ships for Linux and Windows. There's no officially maintained macOS build of qemu-guest-agent, so features like graceful shutdown from the Proxmox GUI and IP address reporting won't work the way they do on other guest types.

What macOS versions actually work?
Most versions from the last several years work with a current OpenCore build, though very new releases can take a few weeks after Apple ships them before OpenCore fully catches up. Check the OSX-KVM project's own compatibility notes for the specific version you're targeting before committing to it.

Conclusion

Running macOS on Proxmox VE is real, it works, and enough people rely on it daily that the rough edges are well documented at this point. It's also not a five-minute job, and it's built entirely on community tooling operating outside both Apple's and Proxmox's official support boundaries.

If you need it for a specific, recurring reason — Xcode builds, cross-platform QA, a Mac-only tool you can't avoid — it's worth the setup time. If you're doing it purely out of curiosity, go in expecting an evening of troubleshooting rather than a quick weekend project, and keep that early snapshot once you get it working.