This is the multi-page printable view of this section. .
macOS Base Image
On a Debian 12 KVM host, install macOS Sonoma by hand using the kholia/OSX-KVM approach, then freeze the resulting disk into a self-contained qcow2 template image for deriving macOS VMs.
- Output:
/home/fish/bucket/kvm/macos/macos-sonoma-base.img - Guest: macOS Sonoma 14.8.9 (x86_64), 4 vCPU / 8 GB, account
admin/admin, Remote Login enabled - OSX-KVM repo (hereafter “repo”):
/home/fish/bucket/OSX-KVM - Recorded: 2026-09-10 (updated 2026-09-20)
Prerequisites
- Host QEMU >= 8.2.2 (10.0.2 here), libvirt >= 9 (11.3.0 here, from bookworm-backports)
/dev/kvmavailable- OSX-KVM repo cloned to the repo path
- VNC client: a VNC viewer on the host’s
DISPLAY=:0, orssh -Lforwarding and connect locally - Disk space: the base image is ~29G actual; installation needs extra space
OVMF choice (important)
During installation you can use OSX-KVM’s bundled OVMF (non-persistent; does not affect the install):
OVMF_CODE_4M.fd(3.5M)OVMF_VARS-1920x1080.fd(128K) — must be the version without the-expsuffix
When blessing + integrating with libvirt you must switch to the host distro’s persistent OVMF:
- code:
/usr/share/OVMF/OVMF_CODE_4M.fd - vars: the 540672-byte persistent VARS file (copied from the VARS written to disk after a real bless)
OSX-KVM’s bundled OVMF is the RAM-backed / EmuVariable variant; it never reads or writes the on-disk VARS file. The
efi-boot-devicevariable written by bless cannot persist, and cold boot always stops at Apple Startup Manager.
1. Download and convert the installer media
2. Create the install directory and disk
qcow2 can be enlarged later:
qemu-img resize xxx.qcow2 128G+ inside the guestdiskutil apfs resizeContainer diskN 0. Starting small does not limit you.
3. Boot the install VM
Using the boot-macos-install.sh script (in /home/fish/bucket/OSX-KVM/):
Start it:
Key points:
- All three disks attach to q35’s built-in AHCI (
ide.0/ide.1/ide.2); do not add anich9-ahcidevice — this keeps the disk controller at PCI1f:2, which is the prerequisite for bless to land correctly (see “Technical background: PCI topology and bless”) snapshot=onprotects the OpenCore disk from modification during installationusb-tabletgives the VNC client absolute pointer positioning (clicks land accurately)- VNC display
:83(port 5983) - Uses the host’s persistent OVMF CODE (
/usr/share/OVMF/OVMF_CODE_4M.fd) so post-bless variables persist to disk
4. Complete the installation over VNC
Connect VNC:
Installation flow (fully manual clicking; prefer the mouse when the keyboard is unreliable):
- OpenCore picker: arrow-key to
macOS Base System, press Enter to enter Recovery - Recovery main window → double-click
Reinstall macOS Sonoma→ Continue (bottom right) - License page → Agree
- Target disk page: if only
macOS Base System(2.87G, the Recovery itself) is listed, the target disk is unpartitioned. Click Back to return to Recovery - Open Disk Utility → menu
View -> Show All Devices→ selectQEMU HARDDISK Media(the whole virtual disk) - Erase: Name
Macintosh HD/ FormatAPFS/ SchemeGUID Partition Map, then close Disk Utility - Enter Reinstall macOS Sonoma again;
Macintosh HDnow appears → Continue - Wait for the install (tens of minutes to an hour+); on
Restart→ click it - Back at the OpenCore picker → choose
Macintosh HD→ first-boot sequence - Setup Assistant:
- Language: English only (smaller language packs)
- Region: any (US/Australia are neutral; avoid odd timezones like American Samoa)
- Keyboard: default
- Migration: Not Now
- Do not install Xcode CLI tools (saves ~1.5G)
- Account: Full Name / Account Name
admin, passwordadmin
Pitfalls:
- On first boot the
vmware-svgadriver produces a grey screen for a few minutes — not a hang - Keyboard navigation in the Recovery main window is unreliable (Tab moves focus, but Space/Return won’t activate list items); list rows need a mouse double-click
- Scripted clicking over VNC (hand-written RFB PointerEvents) is unreliable on QEMU (BrokenPipe); a real VNC client is easiest
5. Size optimization (after install, before bless)
Via SSH or in Terminal:
6. Enable Remote Login (SSH)
System Settings → General → Sharing → Remote Login on; click the i on the
right → allow All users.
macOS has Remote Login off by default; disable the Network Firewall or allow ssh to avoid
kex_exchange_identification: Connection closed.
7. Bless + clean shutdown
This is the key step for keyboard-free cold boot (see “Technical background: PCI topology and bless”).
Inside the macOS guest:
Never hard-kill QEMU — the qcow2 gets dirty and may need journal recovery.
Wait for SSH to drop and the QEMU process to exit on its own (pgrep -f qemu-system returns nothing).
8. Verify and promote the NVRAM template
9. Produce the base image
Verify:
The result is a read-only template. Derive new VMs from it as backing:
Note: macOS APFS on AHCI SATA does not support TRIM (QEMU only supports it on virtio-blk/scsi/nvme), so
fstrimand sparse reclamation fromqemu-img convertare limited. A lean Sonoma install measures ~29G as the floor; it cannot be meaningfully reduced online.
Technical background: PCI topology and bless
This is the most common trap in macOS-on-KVM; understanding it avoids a lot of dead-end debugging.
The problem
Apple boot.efi draws its own Startup Manager (disk picker): if the
persisted efi-boot-device / efi-boot-device-data variables in OVMF are
missing, or the encoded device path does not match the current PCI topology,
it stops and waits for keyboard input.
And libvirt keyboard injection into macOS guests (send-key / QMP
input-send-event) was measured unresponsive across three USB controllers
(default xhci, xhci pinned to bus0, ich9-ehci1 + ich9-uhci1) — pixel-level
screenshot diff AE=0 — while the identical device config works under bare
qemu.
So the correct approach is to make cold boot itself require no keyboard input.
PCI topology matching
The q35 machine type ships with an ICH9 AHCI controller fixed at PCI
1f:2; libvirt’s <controller type='sata'> uses this built-in controller.
The -device ich9-ahci,id=sata in OSX-KVM’s tutorial scripts adds a
second controller at 02:0. A bless under the 02:0 topology produces an
efi-boot-device device-path that does not match inside a libvirt domain on
1f:2 — the picker appears again.
This topology mismatch was once misdiagnosed as “libvirt’s keyboard is broken, blocking integration”; the root cause was always just the device path mismatch.
The correct approach
The install script (boot-macos-install.sh) adds no extra ich9-ahci; disks
attach directly to q35’s built-in AHCI bus (ide.0 / ide.1 / ide.2),
naturally at 1f:2. Bless in this topology writes a device path of
PCI(dev=1f:2)/SATA(port=N)/..., which matches any libvirt domain also using
1f:2.
OpenCore config.plist notes
The NVRAM > Delete list must not contain efi-boot-device /
efi-boot-device-data (keep only boot-args and
ForceDisplayRotationInEFI), otherwise every boot erases them and breaks
bless persistence.
libvirt EFI domain lifecycle pitfall
virsh undefine on a domain with nvram requires --nvram, and that
deletes the VARS file. Because this VARS is a pre-baked template (not
libvirt’s auto-generated blank one), you must re-cp OVMF_VARS-blessed.fd
to the target path before manually re-defining:
The create-vm role re-seeds the VARS on every creation, so the normal role
path is unaffected; only manual XML re-definition needs this ordering.
Technical background: key decisions
- Sonoma over the latest macOS: OSX-KVM’s combination of Intel emulation (Skylake-Client + OpenCore) + Sonoma is the most mature; Intel support narrows starting with Tahoe
- Keep
snapshot=onon OpenCore.qcow2: EFI disk changes never land, avoiding cross-boot pollution - Never share the OVMF_VARS .fd: each VM must get its own copy, or NVRAM conflicts arise
Appendix A: OpenCore boot disk
OpenCore/OpenCore.qcow2 is a pre-built OpenCore boot disk. Key settings:
- SIP disabled:
csr-active-configset to NVRAM Protections disabled - Auto-boot:
Misc > Bootskips the picker (auto-selects the macOS disk after bless) NVRAM > Deletelist: deletes onlyboot-argsandForceDisplayRotationInEFI, and must not deleteefi-boot-device/efi-boot-device-data
Attach at install time:
snapshot=on ensures install-time changes never land on the OpenCore disk,
keeping the boot disk clean.
Appendix B: OSX-KVM repo asset inventory
Repo: kholia/OSX-KVM
Local path: /home/fish/bucket/OSX-KVM
| File | Size | Purpose |
|---|---|---|
fetch-macOS-v2.py |
– | Download macOS recovery images from Apple’s CDN (interactive version pick) |
BaseSystem.dmg |
753M | Original Apple recovery image download |
BaseSystem.img |
3.0G | Raw installer after dmg2img, attached directly to the VM |
OpenCore/OpenCore.qcow2 |
– | Patched OpenCore boot disk (SIP disabled, auto-boot) |
OVMF_CODE_4M.fd |
3.5M | OSX-KVM’s bundled OVMF CODE (non-persistent) |
OVMF_VARS-1920x1080.fd |
128K | OSX-KVM’s bundled OVMF VARS template (non-persistent) |
Repo scripts
| Script | Description |
|---|---|
boot-macos-install.sh |
Base image install boot script (step 3 above) |
boot-macos-ctrl4.sh |
Bless experiment script using q35’s built-in AHCI (1f:2), no extra ich9-ahci |
boot-macos-experiment.sh |
Early experimental install script (128G + extra ich9-ahci 02:0), reference only |
boot-macos-ctrl.sh / ctrl2 / ctrl3 |
Iterations, no longer needed |
boot-macOS-headless.sh |
OSX-KVM’s original GUI boot script |
Appendix C: Disk layout
Appendix D: Asset flow
Measured run log (2026-09-20, this build)
A full execution of the steps above, recording key commands and verification results for future reproduction.
Install-phase network pitfall and fix
The install VM uses QEMU user-net (slirp NAT); inside the guest
ipconfig getifaddr en0 returns 10.0.2.15 — a NAT-internal address the
host can neither ping nor SSH. Fix: add hostfwd=tcp::2222-:22 to the
-netdev user,id=net0 line of boot-macos-install.sh; the host then reaches
the guest via ssh -p 2222 admin@127.0.0.1, with no network topology change
and no manual typing in VNC.
Size optimization (step 5)
Bless verification (step 7)
Key output (confirming a UUID-addressed preboot volume and correct topology):
After shutdown (shutdown -h now; rc=255 is the normal SSH disconnect, not
an error), you must wait for the QEMU process to exit on its own on the
host (verify with pgrep/ps, not pgrep matching your own just-run shell
command), or the VARS file may not be fully flushed.
NVRAM verification (step 8)
Expect Boot0080, with devpath reading
PciRoot()/PCI(dev=1f:2)/SATA(port=2)/... — exactly what was measured this
run (port=2 corresponds to the install disk on ide.2, matching the
topology future libvirt domains use, see “Technical background: PCI topology
and bless”):
Producing the base image (step 9)
Final artifact verification:
Re-confirmed: shrinking the virtual disk from 128G to 64G kept the actual footprint at 29.1G (vs 28.9G measured for the earlier 128G virtual disk — essentially identical). This backs the conclusion stated at the top of this document: the base image cannot be shrunk by adjusting virtual disk size; 29G is the inherent floor for macOS APFS-on-AHCI without TRIM support (see the “Size optimization” and “Technical background” sections).