QUICKEMU_CONF(5)

📦
version 4.9.9 · 4 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 QUICKEMU_CONF(5) — the quickemu <vm>.conf glow-up guide 💖

okay bestie, sit down, grab a boba 🧋 — this is the manual page for quickemu_conf, aka every option and parameter you can put in your quickemu <vm>.conf file. yes it's a 5. you're welcome.

🌸 NAME 🌸

quickemu_conf — all the options and parameters that live inside your quickemu <vm>.conf 💅

✨ DESCRIPTION ✨

so quickemu creates and runs highly optimised desktop virtual machines for Linux, macOS and Windows 🐧🍏🪟. she comes with sensible defaults out of the box, but like… a LOT of configuration options can be overridden in the required config file. and that config file has to, at bare minimum, specify the path to the installation ISO and the QEMU disk for the installed VM. no ISO, no disk, no vibes. periodt.

🎀 OPTIONS 🎀

these are the options and their defaults for the <vm>.conf file, fr fr:

# Lowercase variables are used in the VM config file only
boot="efi"
cpu_cores=""
disk_img=""
disk_size=""
display=""
extra_args=""
fixed_iso=""
floppy=""
guest_os="linux"
img=""
iso=""
macaddr=""
macos_release=""
network=""
port_forwards=()
preallocation="off"
ram=""
secureboot="off"
tpm="off"
usb_devices=()
viewer="spicy"
ssh_port=""
spice_port=""
public_dir=""
monitor="socket"
monitor_telnet_port="4440"
monitor_telnet_host="localhost"
monitor_cmd=""
serial="socket"
serial_telnet_port="6660"
serial_telnet_host="localhost"
# options: ehci(USB2.0), xhci(USB3.0)
usb_controller="ehci"
# options: ps2, usb, virtio
keyboard="usb"
keyboard_layout="en-us"
# options: ps2, usb, tablet, virtio
mouse="tablet"

🌈 EXAMPLES 🌈

a lil Linux moment, look at her go:

guest_os="linux"
disk_img="debian-bullseye/disk.qcow2"
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso"

and the default macOS configuration? it's giving:

guest_os="macos"
img="macos-catalina/RecoveryImage.img"
disk_img="macos-catalina/disk.qcow2"
macos_release="catalina"
  • guest_os="macos" tells Quickemu to optimise for macOS 🍏
  • macos_release="catalina" tells Quickemu to optimise for a particular macOS release.
    • for example, VirtIO Network and Memory Ballooning are available in Big Sur and newer, but not previous releases.
    • and VirtIO Block Media (disks) are supported/stable in Catalina and newer.

the default Windows 11 configuration, iconic as always:

guest_os="windows"
disk_img="windows-11/disk.qcow2"
iso="windows-11/Win11_EnglishInternational_x64.iso"
fixed_iso="windows-11/virtio-win.iso"
tpm="on"
secureboot="on"
  • guest_os="windows" tells quickemu to optimise for Windows 🪟
  • fixed_iso= specifies the ISO image that provides the VirtIO drivers.
  • tpm="on" tells quickemu to create a software emulated TPM device using swtpm.

⚡ BIOS and EFI ⚡

since Quickemu 2.1.0, efi is the default boot option. so if you wanna override that behaviour, add this line to your VM configuration to enable legacy BIOS instead:

  • boot="legacy" — Enable Legacy BIOS boot

🧠 Tuning CPU cores, RAM & disks 🧠

by default, Quickemu calculates the number of CPU cores and RAM to allocate to a VM based on the specs of your host computer. but bestie, you can override that default behaviour and tune the VM configuration exactly to your liking.

just add additional lines to your virtual machine configuration:

  • cpu_cores="4" — Specify the number of CPU cores allocated to the VM
  • ram="4G" — Specify the amount of RAM to allocate to the VM
  • disk_size="16G" — Specify the size of the virtual disk allocated to the VM

💾 Disk preallocation 💾

Preallocation mode — allowed values are off (default), metadata, falloc, full. an image with preallocated metadata is initially larger, but it can improve performance when the image needs to grow. growth spurt but make it storage ✨

specify what disk preallocation should be used, if any, when creating the system disk image, by adding a line like this to your VM configuration:

  • preallocation="metadata"

📀 CD-ROM disks 📀

if you wanna expose an ISO image from the host to the guest, add this line to the VM configuration:

  • fixed_iso="/path/to/image.iso"

🍓 Floppy disks 🍓

if you're like Alan Pope you'll probably want to mount a floppy disk image in the guest. to do so, add this line to the VM configuration:

  • floppy="/path/to/floppy.img"

🫶 File Sharing 🫶

heads up: ALL File Sharing options will only expose ~/Public (or localised variations) for the current user to the guest VMs. that's it. that's the whole share. 🙈

🐧🍏🪟 Samba

if smbd is available on the host, Quickemu will automatically enable the built-in QEMU support for exposing a Samba share from the host to the guest. automatic. slay.

you can install the minimal Samba components on Ubuntu using:

sudo apt install --no-install-recommends samba

if everything is set up correctly, the smbd address will be printed when the virtual machine is started. for example:

 - smbd:     On guest: smb://10.0.2.4/qemu

if you're using a Windows guest, right-click on "This PC", click "Add a network location", and paste this address — but remove smb: and replace the forward slashes with backslashes (in this example that gives you \\10.0.2.4\qemu).

🌐 SPICE WebDAV 🐧🪟

  • TBD

🦋 VirtIO-9P 🐧🍏

  • TBD

🕸️ Networking 🕸️

🔀 Port forwarding

add an additional line to your virtual machine configuration. for example:

  • port_forwards=("8123:8123" "8888:80")

in the example above:

  • Port 8123 on the host is forwarded to port 8123 on the guest.
  • Port 8888 on the host is forwarded to port 80 on the guest.

🚫 Disable networking

to completely disable all network interfaces in a guest VM, add this additional line to your virtual machine configuration:

  • network="none"

🔒 Restricted networking

you can isolate the guest from the host (and the broader network) using the restrict option, which will restrict networking to just the guest and any virtual devices.

this can be used to prevent software running inside the guest from phoning home while still providing a network inside the guest. add this additional line to your virtual machine configuration:

  • network="restrict"

🌉 Bridged networking

connect your virtual machine to a preconfigured network bridge. add an additional line to your virtual machine configuration:

  • network="br0"

if you want a persistent MAC address for your bridged network interface in the guest VM, you can add macaddr to the virtual machine configuration. QEMU requires that the MAC address is in the range: 52:54:00:AB:00:00 - 52:54:00:AB:FF:FF

so you can generate your own MAC addresses with:

  • macaddr="52:54:00:AB:51:AE"

🔌 USB redirection 🔌

Quickemu supports USB redirection via SPICE pass-through and host pass-through. Quickemu supports USB redirection via SPICE pass-through and host pass-through. (yes she said it twice, she's just that serious about it 💀)

NOTE! When a USB device is redirected from the host, it will not be usable by the host operating system until the guest redirection is stopped. Therefore, do not redirect the input devices, such as the keyboard and mouse, as it will be difficult (or impossible) to revert the situation. bestie I am BEGGING you, do not redirect your keyboard. 😭

using SPICE for USB pass-through is easiest as it doesn't require any elevated permission. no sudo, no drama. 👑

both spicy from spice-gtk (Input -> Select USB Devices for redirection) and remote-viewer from virt-viewer (File -> USB device selection) support this feature.

  • Start Quickemu with --display spice and then
  • Select Input -> Select USB Device for redirection from the menu to choose which device(s) you want to attach to the guest.
  • **spicy (default)
    • **Select Input -> Select USB Device for redirection from the menu to choose which device(s) you want to attach to the guest.
  • **remote-viewer
    • **Select File -> USB device selection from the menu to choose which device(s) you want to attach to the guest.

to ensure that this functionality works as expected, make sure that you have installed the necessary SPICE Guest Tools on the virtual machine.

❄️ Enabling SPICE redirection on NixOS

on NixOS, if you encounter this error:

Error setting facl: Operation not permitted

try setting the following option:

virtualisation.spiceUSBRedirection.enable = true;

USB host redirection is not recommended, it is provided purely for backwards compatibility to older versions of Quickemu. using SPICE is preferred, see above. 👆

add an additional line to your virtual machine configuration. for example:

  • usb_devices=("046d:082d" "046d:085e")

in the example above:

  • The USB device with vendor_id 046d and product_id 082d will be exposed to the guest.
  • The USB device with vendor_id 046d and product_id 085e will be exposed to the guest.

if the USB devices are not writable, quickemu will display the appropriate commands to modify the USB device(s) access permissions, like this:

 - USB:      Host pass-through requested:
              - Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes:
                sudo chown -v root:user /dev/bus/usb/001/005
                ERROR! USB permission changes are required 👆

🔐 TPM 🔐

since Quickemu 2.2.0 a software emulated TPM device can be added to guest virtual machines. just add tpm="on" to your VM configuration. quickget will automatically add this line to Windows 11 virtual machines. so thoughtful of her 💜

👑 AUTHORS 👑

Written by Martin Wimpress.

🐛 BUGS 🐛

Submit bug reports online at: https://github.com/quickemu-project/quickemu/issues

💅 SEE ALSO 💅

Full sources at: https://github.com/quickemu-project/quickemu

quickget(1), quickemu(1), quickgui(1)

👑 AUTHORS (again, because she said it twice) 👑

Martin Wimpress.

and that's the whole page bestie!! 💖 this lil doc is quickemu_conf, dated February 2, 2026, from the QUICKEMU_CONF(5) manual — go forth and configure your VMs, you absolute icon 🎀✨🦋

📦 where this page comes from