Using the UTM virtualization app

UTM is a macOS/iOS GUI for running virtual machines. On macOS it has two backends:

• QEMU — full emulation of 30+ architectures (x86_64, ARM64, RISC-V, PPC, …) plus HVF acceleration when host and guest architectures match. Required for Windows, BSDs, classic OSes, and anything cross-architecture. Supports USB pass-through, snapshots, port forwarding, custom QEMU args, and full automation (input, exec, files, IP).
• Apple Virtualization (Virtualization.framework) — native, very fast, but limited to macOS guests on Apple Silicon and modern Linux guests. No USB pass-through, no scripted input, no guest-agent file/exec.

A VM is stored as a .utm bundle (a directory). User VMs live in ~/Library/Containers/com.utmapp.UTM/Data/Documents/. Backups are just file copies of the bundle.

There are three ways to drive UTM from a script:

1. utmctl — bundled CLI at /Applications/UTM.app/Contents/MacOS/utmctl (also linked as utmctl in some installs). Best for shell automation. See references/utmctl.md.
2. AppleScript / JXA — full scripting dictionary in UTM.sdef. Needed for input automation, configuration edits, and creating VMs. See references/applescript.md.
3. Bundle / config edits — when UTM is closed you can read or rewrite config.plist inside a .utm bundle directly. See references/configuration.md.

For end-user workflows (installing Linux, Windows, macOS guests; networking; file sharing) see references/workflows.md. For known gotchas and performance tuning see references/troubleshooting.md.

Gotchas — read these before automating