Technology And Ramblings

Modifying UTM Configuration Via CLI

Tags: #UTM #virtualization

Note: A follow-up to blog post Booting Arch Linux Using Apple Virtualization Framework With UTM.

Tested on UTM version 4.2.5 and macOS 13.4.

Warning: Backup the configuration before editing manually!


Apple virtualization backend is used in this blog post.

Things might change with future releases of UTM or macOS.

Consult the documentation for the latest information.

Virtual Machine Bundle Format

UTM stores virtual machines at $HOME/Library/Containers/com.utmapp.UTM/Data/Documents/.

Virtual machines managed by UTM are bundled in a .utm format, which is a directory:

file 'Arch Linux.utm'
Arch Linux.utm: directory

This directory contains all files related to the virtual machine configuration and data:

tree 'Arch Linux.utm'
Arch Linux.utm
├── Data
│   ├── 86BDC3C3-E94C-446F-A9E2-A323BAF582D1.img
│   └── Image-archboot-aarch64
└── config.plist

Virtual machine configuration is stored in config.plist, in a plist format.

Virtual machine data is stored in the Data directory.
From the example above, 86BDC3C3-E94C-446F-A9E2-A323BAF582D1.img represents a storage device, and Image-archboot-aarch64 is a kernel binary used to boot the operating system.

Exploring config.plist

Since the configuration file is a plist (an XML), we can easily interact with it using the native /usr/libexec/PlistBuddy utility to look up and modify the configuration.

Query Configuration

We can use the print command in /usr/libexec/PlistBuddy to print the configuration:

/usr/libexec/PlistBuddy -c print 'Arch Linux.utm/config.plist'
Dict {
    Serial = Array {
    Backend = Apple
    System = Dict {
        CPUCount = 4
        Boot = Dict {
            LinuxCommandLine = console=hvc0 root=/dev/vda2
            LinuxKernelPath = Image-archboot-aarch64
            OperatingSystem = Linux
            UEFIBoot = false
        GenericPlatform = Dict {
            machineIdentifier = bplist00TUUIDOdcH;F
        Architecture = aarch64
        MemorySize = 8192
    ......output omitted......

It is possible to access a key directly as well:

/usr/libexec/PlistBuddy -c 'print Backend' 'Arch Linux.utm/config.plist'

We can also access nested keys:

/usr/libexec/PlistBuddy -c 'print System:Boot' 'Arch Linux.utm/config.plist'
Dict {
    LinuxCommandLine = console=hvc0 root=/dev/vda2
    LinuxKernelPath = Image-archboot-aarch64
    OperatingSystem = Linux
    UEFIBoot = false

Modifying Configuration

Any modification to the virtual machine is stored in config.plist.

The UTM’s graphical interface allows modifying the virtual machine configuration (Left mouse click on virtual machine -> Edit). Graphical User Interface of a virtual machine edit screen in UTM

Modifying config.plist directly is possible.

For example, we can increase the RAM size:

# Getting the current virtual memory size
/usr/libexec/PlistBuddy -c 'print System:MemorySize' 'Arch Linux.utm/config.plist'
# Result
# Configure a new virtual memory size
/usr/libexec/PlistBuddy -c 'set System:MemorySize 16384' 'Arch Linux.utm/config.plist'
# Get the new value
/usr/libexec/PlistBuddy -c 'print System:MemorySize' 'Arch Linux.utm/config.plist'

After restarting the UTM app (may not be required), the change is reflected in the GUI: Modified configuration of virtual machine applied from the previous step

Example, Remove Console And Display For Headless Operation

By default, all virtual machines created by UTM will have a console and display devices attached to them:

# Default display device
/usr/libexec/PlistBuddy -c 'print Display' 'Arch Linux.utm/config.plist'
Array {
    Dict {
        WidthPixels = 1920
        PixelsPerInch = 80
        HeightPixels = 1200
# Default console (serial) device
/usr/libexec/PlistBuddy -c 'print Serial' 'Arch Linux.utm/config.plist'
Array {
    Dict {
        Mode = Terminal
        Terminal = Dict {
            BackgroundColor = #000000
            Font = Menlo
            CursorBlink = true
            FontSize = 12
            ForegroundColor = #ffffff

When starting the virtual machine through utmctl start 'Arch Linux', it will attach the display and console devices.

Users may want to interact with the system headlessly via remote management without needing a display or console devices.
We can remove the array elements inside the Serial and Device keys to remove these devices from a virtual machine:

# Remove display devices
/usr/libexec/PlistBuddy -c 'delete Display:' 'Arch Linux.utm/config.plist'
# Remove console devices
/usr/libexec/PlistBuddy -c 'delete Serial:' 'Arch Linux.utm/config.plist'

After removal, the keys should look like this:

# View display configuration
/usr/libexec/PlistBuddy -c 'print Display' 'Arch Linux.utm/config.plist'
Array {
# View console configuration
/usr/libexec/PlistBuddy -c 'print Serial' 'Arch Linux.utm/config.plist'
Array {

From now on, virtual machines started by UTM will not attach any display or console.

Final Notes

This post briefly explored UTM’s configuration, how to modify it via CLI, and small snippets of configurations. not attach any display or console.

Back To Top