UTM Logo

Guide

Creating a virtual machine

In the main window, press the “+” button on the top toolbar next to the title. You have the option to browse the gallery (recommended for new users) or to create a new VM from scratch. If you choose to create from scratch, most users do not need to change any options except from the Information tab, the System tab, and the Drives tab. All the other tabs are for more advanced use cases and the options should be set to the recommended default.

Information

When creating a new VM from scratch, you will see the same screen as when modifying an existing VM’s configuration. In the Information tab, you should give your VM a Name and optionally assign an icon to identify your VM by. The name must be unique as it is also the name of the .utm package which contains all data corresponding to this VM.

You can also write any Notes that will be displayed in the home screen when the VM is selected.

System

In the System tab, you can configure the Architecture, System, and Memory. The architecture is the CPU and determines what operating systems you can run. The most common architecture is x86_64, which is used by modern Intel and AMD processors (most PCs) and is used by most versions of Windows and Linux.

When you change the architecture to a well-known one, other settings will change to the default recommended settings so in most cases you do not have to manually change any of the other settings (except Memory and Drives).

The System drop-down lets you fine tune the emulated system to be a specific model or device. Most users should not have to change this from the default.

You should not assign more memory than the amount of physical RAM on your computer or you may experience slowdowns or even crashes. It is recommended that you assign no more than half the amount of physical RAM if you do not want to significantly affect the performance of your Mac.

Most users should not touch the Advanced Settings, but there you can fine tune parts of the emulation.

QEMU

The QEMU tab is only for advanced use cases and for debugging emulation issues. You can choose to enable debug logging and to export the last debug log (created when the VM starts). You can also export the full QEMU command generated by UTM for the current configuration. If you choose to Bypass Configuration, then all other configuration options (including attached drives) will be ignored! This option should only be used for debugging.

Drives

You can create and mount virtual drives for the VM in the Drives tab. Import Drive will let you select a file to mount and New Drive will let you create either an empty removable drive or an empty hard drive.

If you wish to mount an ISO disk image, it is recommended that you create a New Drive and check Removable. You can then select the ISO image from the home screen or while the VM is running. If you choose to Import the ISO, then you cannot change the mounted disk image while the VM is running.

If you choose to Import Drive, it is recommended that you import a QCOW2 formatted drive image. Most other common disk image formats are compatible with QEMU but you will not be able to suspend a running VM when you have non-removable non-QCOW2 images mounted.

If you create a New Drive you can choose the Interface to attach the drive to. Most users can leave the default here as only advanced use cases require changing the interface.

The listed order of the drives are the same order exposed to QEMU which can affect boot order. You can re-order drives by using the arrow buttons.

Display

The Display tab provides options to showing the VM’s output. Full Graphics emulates a display card while Console Only emulates a serial console. Full Graphics is not supported for all architectures and if it is not supported, it will be grayed out.

In Full Graphics, the Emulated Display Card will be set to be recommended default. Most users should not change this. The Scaling options control what hardware scalers are used when resizing the VM window. Most users should not change this.

In Console Only mode, you can change aspects of the terminal display. The Resize Console Command is a string that is sent to the serial input when the Resize button is pressed while the VM is running. The command is different depending on the guest operating system, but should be used to inform the OS that the console size has changed and to render UI elements accordingly. The default command should work in most Linux distributions.

Input

The Input tab gives the option for Legacy mode which should only be enabled for ancient operating systems (such as DOS) which does not support USB. Invert Mouse Scroll can be used to invert the emulated scroll wheel.

Network

If networking is unsupported by the emulated architecture, these options will be disabled. Advanced Options allow you to configure the guest network subnet and does not need to be used in most cases.

Port Forward lets you forward ports from the guest subnet to your local (host) machine.

Sound

If sound is unsupported by the emulated architecture, these options will be disabled. Emulated Audio Card should be set to the recommended default and can be changed for advanced use cases.

Sharing

If SPICE Guest Tools are installed in the guest OS, clipboard sharing and directory sharing can be used. If the tools are not installed, these features will not work even if enabled. The shared directory can be specified in the home screen.

Managing virtual machines

From the home screen, you can re-order the VM list by dragging the VM entry around. A secondary click on a VM will open a menu of options such as Delete, Clone, and Edit. You can also show the VM’s package location in Finder.

When a VM is selected, the top right toolbar provides similar operations.

To Start a VM, you can press the small play button on the right of the VM entry or the large play button when the VM is selected.

Using a virtual machine

Once started, there are a few buttons in the toolbar for controlling the virtual machine.

Power

Powers off the VM with a force power off.

Suspend

Only works if all non-removable drives are QCOW2 drive images AND the current VM is not virtualized (the guest and host architecture are the same). This allows you to save the state of the VM and the next time you start it, it will resume from this point instead of booting up fresh.

Restart

Force restarts the VM.

Capture Mouse

Not available in console mode. Fully captures mouse and keyboard input and redirects it to the VM. To exit this mode, press Control+Option key at once.

Resize

Only available in console mode. Sends the Resize Console Command configured in the Display tab of the settings screen. This allows you to notify the guest operating system that the console size changed and that UI can be rendered correctly.

Disk Image

Opens the disk image menu which allows you to change or eject the removable disk image. Only drives marked Removable (in Drives settings) support this.

Shared Directory

If Shared Directory is enabled (in Sharing settings) and the SPICE Guest Tools are installed in the guest operating system, this allows you to change the shared directory to be accessed in the guest.

UTM Preferences

You can access the preferences with Cmd+, or from the UTM menu. This allows you to change global emulation options including the option to disable virtualization (automatically enabled if the guest and host architecture are the same).

Help and Support

See here for more information.