macOS — V\OS Docs

Running Vitruvian in a VM on macOS is close to the same experience as the Linux and Windows guides, because the project develops against QEMU on all three hosts. Two things differ: acceleration comes from Apple’s Hypervisor framework (HVF), and the image you pick depends on your chip.

What you need

A Mac with hardware virtualization. Your chip decides which image to use, covered below.
At least 8 GB of RAM on the host. The example commands give the guest 4 GB.
QEMU. Homebrew is the standard way to install it if you don’t have it already: brew install qemu.

Which image?

Intel Macs use the amd64 image, same as on Linux and Windows.
Apple Silicon Macs use the arm64 image. It’s the same build made for single-board computers (see the boards site), and it runs natively under HVF. The amd64 image does boot on Apple Silicon, but only through full emulation, which is noticeably slower.

Check that HVF is available before you start:

bash

sysctl kern.hv_support

A value of 1 means the Hypervisor framework is ready. If you get 0, virtualization is unavailable (uncommon on real Macs; more common inside a nested VM) and you’ll fall back to emulation, detailed below.

Boot a raw image

bash

qemu-system-x86_64 \
  -cdrom vitruvian.img -boot menu=on \
  -m 4G -cpu host -smp sockets=1,cores=2,threads=2 -accel hvf \
  -netdev user,id=mynet,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=mynet \
  -audiodev id=snd0,driver=coreaudio -device ich9-intel-hda \
  -device hda-output,audiodev=snd0

On Apple Silicon, use qemu-system-aarch64 with the arm64 image instead:

bash

qemu-system-aarch64 \
  -cdrom vitruvian-arm64.img -boot menu=on \
  -m 4G -cpu host -smp sockets=1,cores=2,threads=2 -accel hvf \
  -netdev user,id=mynet,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=mynet \
  -audiodev id=snd0,driver=coreaudio -device ich9-intel-hda \
  -device hda-output,audiodev=snd0

Boot an ISO

Same setup, pointing at the ISO instead of a raw image:

bash

qemu-system-x86_64 \
  -cdrom vitruvian.iso -boot menu=on \
  -m 4G -cpu host -smp sockets=1,cores=2,threads=2 -accel hvf \
  -netdev user,id=mynet,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=mynet \
  -audiodev id=snd0,driver=coreaudio -device ich9-intel-hda \
  -device hda-output,audiodev=snd0

Everything else from the Linux guide carries over unchanged, including the SSH port forward.

SSH into the guest

The hostfwd=tcp::2222-:22 line forwards the guest’s SSH port to localhost:2222. From a normal terminal:

bash

ssh -p 2222 vitruvian@127.0.0.1

Troubleshooting

“HVF is not available”: sysctl kern.hv_support should return 1 before you bother. If you’re on a real Mac and it returns 0, you’re likely already inside a virtualized environment. Either way, drop -accel hvf and the guest runs under emulation, just slower.
Apple Silicon feels sluggish: you’re almost certainly running the amd64 image, which can’t use HVF there. Switch to the arm64 image.
The window opens and closes instantly: check the terminal output for the real error, usually a typo in a path or flag. With -boot menu=on you should at minimum reach the boot menu.
No sound / no network: those need the -audiodev and -netdev lines present on the command line; they’re easy to drop accidentally and nothing fails loudly when they’re missing.

Most issues at this stage are small command-line slips, and the error message in the terminal names the culprit.

V\OS Docs