QEMU and Firmware Detection

Cubic relies on QEMU and UEFI firmware to create and run virtual machines. When you start a VM, Cubic automatically searches for these tools in standard locations. This page explains where Cubic looks and how to override the detected paths when needed.

QEMU Binary

Cubic searches for the QEMU system emulator on your PATH. The binary name depends on the architecture of the virtual machine:

Architecture	Binary
amd64	qemu-system-x86_64
arm64	qemu-system-aarch64

Install QEMU if it is not already present:

Platform	Command
Debian / Ubuntu	sudo apt install qemu-system
Fedora / RHEL	sudo dnf install qemu-system-x86
Arch Linux	sudo pacman -S qemu-full
openSUSE	sudo zypper install qemu
macOS (Homebrew)	brew install qemu
Windows	Install from https://www.qemu.org/download/#windows

Override

Set CUBIC_QEMU to use a QEMU binary that is not on PATH:

$ CUBIC_QEMU=/opt/qemu/bin/qemu-system-x86_64 cubic start my-vm

qemu-img

Cubic searches for qemu-img on your PATH. This tool is used to create and resize virtual machine disk images. It is included with QEMU on all platforms.

Install qemu-img if it is not already present:

Platform	Command
Debian / Ubuntu	sudo apt install qemu-utils
Fedora / RHEL	sudo dnf install qemu-img
Arch Linux	sudo pacman -S qemu-img
openSUSE	sudo zypper install qemu-tools
macOS (Homebrew)	brew install qemu
Windows	Install from https://www.qemu.org/download/#windows

Override

Set CUBIC_QEMU_IMG to use a qemu-img binary that is not on PATH:

$ CUBIC_QEMU_IMG=/opt/qemu/bin/qemu-img cubic create my-vm --image ubuntu:noble

UEFI Firmware

Cubic requires a UEFI firmware image (OVMF for amd64, AAVMF for arm64) to boot virtual machines. Cubic searches a list of well-known paths in order and uses the first file that exists.

AMD64 (OVMF)

Path	Platform
$SNAP/usr/share/OVMF/OVMF_CODE_4M.fd	Snap package
<qemu-root>/share/qemu/edk2-x86_64-code.fd	QEMU install directory
/usr/share/OVMF/OVMF_CODE_4M.fd	Debian / Ubuntu
/usr/share/edk2/ovmf/OVMF_CODE.4m.fd	Fedora / RHEL
/usr/share/edk2-ovmf/OVMF_CODE.fd	Fedora (older)
/usr/share/edk2/x64/OVMF_CODE.4m.fd	Arch Linux
/usr/share/qemu/ovmf-x86_64-code.bin	openSUSE
/opt/homebrew/share/qemu/edk2-x86_64-code.fd	Homebrew (Apple Silicon)
/usr/local/share/qemu/edk2-x86_64-code.fd	Homebrew (Intel)
/home/linuxbrew/.linuxbrew/share/qemu/edk2-x86_64-code.fd	Linux Homebrew (non-root)
C:/Program Files/QEMU/share/edk2-x86_64-code.fd	Windows

Install OVMF if it is not already present:

Platform	Command
Debian / Ubuntu	sudo apt install ovmf
Fedora / RHEL	sudo dnf install edk2-ovmf
Arch Linux	sudo pacman -S edk2-ovmf
openSUSE	sudo zypper install qemu-ovmf-x86_64
macOS (Homebrew)	brew install qemu
Windows	Install from https://www.qemu.org/download/#windows

ARM64 (AAVMF)

Path	Platform
$SNAP/usr/share/AAVMF/AAVMF_CODE.fd	Snap package
<qemu-root>/share/qemu/edk2-aarch64-code.fd	QEMU install directory
/usr/share/AAVMF/AAVMF_CODE.fd	Debian / Ubuntu
/usr/share/edk2/aarch64/QEMU_EFI-pflash.raw	Fedora / RHEL
/usr/share/edk2-armvirt/aarch64/QEMU_EFI.fd	Arch Linux
/usr/share/qemu/aavmf-aarch64-code.bin	openSUSE
/opt/homebrew/share/qemu/edk2-aarch64-code.fd	Homebrew (Apple Silicon)
/usr/local/share/qemu/edk2-aarch64-code.fd	Homebrew (Intel)
/home/linuxbrew/.linuxbrew/share/qemu/edk2-aarch64-code.fd	Linux Homebrew (non-root)
C:/Program Files/QEMU/share/edk2-aarch64-code.fd	Windows

Install AAVMF if it is not already present:

Platform	Command
Debian / Ubuntu	sudo apt install qemu-efi-aarch64
Fedora / RHEL	sudo dnf install edk2-aarch64
Arch Linux	sudo pacman -S edk2-armvirt
openSUSE	sudo zypper install qemu-uefi-aarch64
macOS (Homebrew)	brew install qemu
Windows	Install from https://www.qemu.org/download/#windows

Override

Set CUBIC_FW to use a firmware file that was not found by autodetection. This bypasses the entire candidate search:

$ CUBIC_FW=/usr/share/OVMF/OVMF_CODE.fd cubic start my-vm

Environment Variable Reference

Variable	Tool	Description
CUBIC_QEMU	QEMU emulator	Path to the qemu-system-* binary to use instead of the one found on PATH
CUBIC_QEMU_IMG	qemu-img	Path to the qemu-img binary to use instead of the one found on PATH
CUBIC_FW	UEFI firmware	Path to the OVMF or AAVMF firmware file to use instead of the autodetected path