Introduction

quickemu-rs is a collection of two Rust programs, quickget and quickemu, each of which are designed to simplify the creation and running of Virtual Machines. This documentation specifically covers the usage of these two programs in their CLI forms, including configuration options.

quickemu-rs uses QEMU under the hood to allow for large amounts of configurability.

Installation

Arch Linux

quickemu-rs is officially maintained on the AUR; you can install it with your favourite AUR helper.

For instance,

paru -S quickemu-rs

Dependencies

quickemu-rs depends on QEMU, which must be compiled with GTK, SDL, SPICE, and VirtFS support. By default, smartcard support is also required, and the minimum QEMU version is 8.1.0.

If you are building from source, you can optionally disable the smartcard_args and qemu_8_1 features, which will remove these requirements.

Binaries

Pre-built binaries are available for macOS and GNU/Linux on the releases page. To install, download the archive for your platform, extract it, and copy the binaries to a directory in your $PATH, such as ~/.local/bin.

Compilation from source

Alternatively, you can manually compile from source. To do so, you will need to have Rust installed. For more information on how to install Rust, see the official Rust website.

Once you have installed Rust, you can clone the repository and build the project:

git clone https://github.com/lj3954/quickemu-rs.git
cd quickemu-rs
cargo build --release

This will compile the 2 binaries into the target/release directory. Then, you can copy the binaries into a directory in your $PATH.

Quickget

Quickget is responsible for downloading operating system images from pre-generated URLs, and creating sensible configurations which can be passed into quickemu.

Since all available operating systems are fetched from the internet, quickget may be slow on its first launch each day. Configurations are cached and will be refreshed if quickget hasn't been run since UTC midnight.

Usage

Running quickget-rs without any arguments will list all available operating systems. Then, you can pass in an operating system to list all available releases and (if applicable) editions.

Following that, you can easily download an operating system and create a configuration by passing in the operating system, release, and edition (if applicable).

For example, to create a VM running Kubuntu 24.04 LTS:

quickget-rs kubuntu 24.04

CLI arguments

Quickemu

Quickemu is responsible for launching virtual machines using configuration files.

Configuration files are TOML formatted, information about their usage can be found in the configuration docs.

Usage

Run quickemu-rs followed by a path to a configuration file.

For example,

quickemu-rs ubuntu-24.04-x86_64.toml

Quickemu can be configured primarily by editing the configuration file, which is TOML formatted.

Guest OS

Specifying a Guest OS allows quickemu to select compatible hardware devices, optimize performance, and enable features supported on different guest operating systems.

The field can be edited as so.

[guest]
os = "macos"
# On certain operating systems, other fields can be present here.
# For example, macOS requires a release to select compatible emulated hardware.
release = "sequoia"

VM Directory and Name

The VM's name can be set through the 'vm_name' entry in the configuration file.

The VM's directory can be set through the 'vm_dir' entry.

If either are unpopulated, they will be set based on the other, or if unavailable, the configuration file's name.

Machine configuration

Quickemu allows for various customizations to the emulated machine.

All options within this category must be under [machine] in your configuration file.

CPU threads

Quickemu will automatically detect whether your CPU supports SMT, and configure your VM in the same way. On a system with SMT, an odd number of threads will be rounded down.

You can set the amount of total CPU threads the VM should receive as such.

cpu_threads = 8

RAM

Quickemu supports configuring sizes, such as RAM, using both integers (in bytes), as well as strings representing a size, with binary-prefix units.

For example, the configuration below will allocate 8 GiB of memory to your VM.

ram = "8G"

Boot Types

Quickemu defaults to EFI boot with secure boot disabled. Legacy BIOS and Secure Boot are both supported.

You can configure quickemu to use legacy BIOS as follows

[machine.boot]
type = "legacy"

Alternatively, to enable secure boot, you can modify the configuration as follows. Note that you must explictly specify the EFI boot type in order to enable secure boot.

[machine.boot]
type = "efi"
secure_boot = true

TPM

Quickemu supports TPM 2.0, using swtpm for emulation. It can be configured as follows

tpm = true

Status Quo

This option marks all disks attached to the VM as read-only, ensuring they are not modified while the VM is running.

status_quo = true

IO devices

Quickemu supports configuration of the IO devices emulated to the guest.

All options within this category must be under [io] in your configuration file.

Overriding Guest-selected IO devices

USB Controller

Certain guests (in specific, macOS) may break with non-default USB controllers. You can also disable the USB controller:

usb_controller = "none"

Keyboard

keyboard = "virtio"

Mouse

mouse = "tablet"

Sound Card

sound_card = "intel_hda"

Keyboard Layout

Quickemu, through QEMU, supports emulating various keyboard layouts to the guest. The default is 'en-us'

keyboard_layout = "fr"

Public Directory

You can modify which directory is shared with the VM. The default currently is ~/Public. You can also disable sharing a directory:

public_dir = "none"

Display

Display is a subcategory of io. Therefore, all display configuration must be put under [io.display]

Display Types

Available display types are as follows

none, sdl, gtk, spice, spice_app, cocoa

Cocoa is specific to macOS, while quickemu builds without spice support on macOS targets due to the lack of spice support in the homebrew QEMU package.

Spice

Spice displays (not to be confused with spice app) have certain other configuration options.

type = "spice"
# The port spice can be accessed through
spice_port = 5930
# The IP address spice can be accessed through
access = "127.0.0.1"
# The spice viewer for quickemu to launch after the VM starts
viewer = "remote"

Resolution

Resolution can be set in multiple ways.

You can fully customize it with a width & height as follows:

[io.display.resolution]
type = "custom"
width = 1920
height = 1080

You can also enable fullscreen

[io.display.resolution]
type = "fullscreen"

Or (with the display_resolution feature flag - enabled by default):

[io.display.resolution]
type = "display"
# Optionally, set which display to base the resolution off
# display_name = "Example"
# And, a percentage of the display
# percentage = 60.5

Acceleration

Hardware acceleration in the guest can be manually enabled as follows:

accelerated = true

Note that some guest OSes (e.g. macOS) may override this option due to their reliance upon emulated display devices which do not support hardware acceleration.

Braille

Quickemu can output braille when this option is set

braille = true

Images

All paths can be either absolute or relative to the VM directory

ISO/IMG

ISO and IMG files can be mounted as follows:

[[images.iso]]
path = "ubuntu-24.04.iso"

[[images.img]]
path = "RecoveryImage.img"

Alongside the path, you can add 'always_mount = true' if the image is to be mounted even after the operating system is installed (determined through disk size).

Disks

Disk images can be mounted as follows:

path = "disk.qcow2"
# Optional; default dependent on Guest OS
# Size, much like RAM (read above) can be either set as an integer number of bytes
# or a string representing a size with binary-prefix units
size = "30G"
# Optional; defaults to qcow2
format = "raw"
# Optional; defaults to off. NOTE: Requires disk format to be set
preallocation = "full"

Disks will be created using qemu-img if they do not already exist.

Networking

All options here must be placed under [network] in your config file.

Disable networking

type = "none"

NAT

type = "nat"
# Set a desired SSH port. By default, 22220 will be used
ssh_port = 22220
# Restrict networking to only the guest and virtual devices
restrict = true

# Set each port forward in the array like this
[[network.port_forwards]]
host = 8080
guest = 8080

Bridged

type = "bridged"
# You must specify a bridge interface
bridge = "br0"
# Optionally specify a mac address. Must be in the range 52:54:00:AB:00:00 - 52:54:00:AB:FF:FF
mac_addr = "52:54:00:AB:51:AE"

Monitor and Serial

The QEMU monitor and serial outputs can each be manually configured. By default, they will use unix sockets with a path in your VM directory.

Socket

[network.serial]
type = "socket"
socketpath = "vm-socket.sock"

Telnet

[network.monitor]
type = "telnet"
# The Telnet address has a default value unique to each monitor and serial.
# To manually specify, include a full socket address, including both an IP address and port
address = "127.0.0.1:4440"