Guides
Build and run

Run darwinOS in UTM

Boot darwinOS inside UTM — the macOS-native QEMU frontend. The most convenient option if you're developing on a Mac.

UTM is a macOS app that wraps QEMU in a native UI. It’s the most convenient option on Apple Silicon because it uses the Hypervisor.framework for near-native speed and handles EFI firmware setup for you. If you’re not on a Mac, the QEMU guide is a better fit.

This guide assumes you’ve already built darwinOS from source.

Install UTM

The easiest way is via the App Store or the official download:

  • App Store: search for “UTM Virtual Machines”
  • Direct download: mac.getutm.app

UTM is free from both sources; the App Store version is a convenience for easier updates.

Create a VM

  1. Launch UTM and click Create a New Virtual Machine.
  2. Choose Virtualize (not Emulate) when running arm64 on Apple Silicon. On Intel Macs emulating arm64, pick Emulate instead — it’s slow but it works.
  3. On the OS screen, pick Other — we won’t use UTM’s preset kernels.
  4. Set:
    • Memory: 4096 MB (or more)
    • CPU cores: 4
    • Storage: point to your built rootfs.img. In the Import dropdown pick “Existing file” and select build/arm64-debug/rootfs.img.
    • Share folder (optional but recommended): pick a host directory you want mounted in the guest.
  5. Save the VM and open its settings before you boot.

Point UTM at the kernel and initrd

In the VM settings, under QEMU → Additional Arguments, add the kernel boot arguments:

-kernel /path/to/build/arm64-debug/kernel.img
-initrd /path/to/build/arm64-debug/initrd.img
-append "console=hvc0 root=/dev/vda"

Use absolute paths — UTM doesn’t resolve relative ones.

Under Display, set Emulated Display Card to virtio-gpu-pci and Console Mode to Serial.

Boot the VM

Click the play button. UTM opens a console window that shows the kernel boot log, followed by launchd, followed by a shell prompt. If the console stays blank for more than 30 seconds, open the VM’s log (gear icon → Logs) to see what QEMU is complaining about.

Shared folders

If you added a shared folder during setup, mount it in the guest with:

mount -t 9p share /mnt

Where share is whatever mount tag you chose. This is the fastest iteration loop on macOS — edit on the host, recompile, run on the guest, no copying.

Snapshots

UTM exposes snapshots via the gear icon → Snapshots while the VM is running. Take one right after boot so you can jump back to a clean state without booting from scratch.

Common problems

“Failed to allocate device memory”

Apple Silicon Macs can’t virtualise arm64 guests with certain memory layouts. Drop the RAM allocation to 2048 MB and try again; some M1 and M2 configurations hit this at 4 GB+.

Boot log cuts off

UTM’s console has a scrollback limit. For full logs, run QEMU from the command line with -nographic (see the QEMU guide) and redirect to a file.

Keyboard input doesn’t reach the guest

Click into the console window once after boot. UTM’s display doesn’t always auto-focus when the VM first starts.

Next steps