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.

How Cubic looks

Cubic builds a single ordered list of directories where QEMU may live:

CUBIC_QEMU_DIR (if set),
every directory on your PATH,
the built-in fallback locations: C:\Program Files\qemu on Windows, and /usr/bin, /usr/local/bin, /opt/homebrew/bin, /home/linuxbrew/.linuxbrew/bin and /opt/local/bin on Unix.

That list is used two ways. For the binaries, Cubic hands the list to QEMU as its PATH (only for the child process, your own environment is left untouched) and launches qemu-system-x86_64 / qemu-system-aarch64 / qemu-img by name, letting the operating system resolve them. For the firmware, Cubic finds the QEMU install from the same list and reads its firmware descriptors (see below).

QEMU Binary

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 qemu-utils ovmf qemu-efi-aarch64`
Fedora / RHEL	`sudo dnf install qemu-system-x86 qemu-img edk2-ovmf edk2-aarch64`
Arch Linux	`sudo pacman -S qemu-full edk2-ovmf edk2-armvirt`
openSUSE	`sudo zypper install qemu qemu-tools qemu-ovmf-x86_64 qemu-uefi-aarch64`
macOS (Homebrew)	`brew install qemu`
Windows	`winget install SoftwareFreedomConservancy.QEMU`

On Linux the UEFI firmware (OVMF for amd64, AAVMF for arm64) is a separate package. The commands above install it alongside QEMU. On macOS (Homebrew) and Windows the firmware is bundled with QEMU.

Override

Set CUBIC_QEMU_DIR to the directory that holds your QEMU binaries. Cubic puts it at the front of the search list (for the binaries and the firmware lookup below):

$ CUBIC_QEMU_DIR=/opt/qemu/bin cubic start my-vm

qemu-img

Cubic runs qemu-img from the same QEMU install as the emulator. This tool is used to create and resize virtual machine disk images. It is included with QEMU on all platforms, so installing QEMU (see above) is enough.

UEFI Firmware

Cubic requires UEFI firmware to boot virtual machines. Rather than guessing filenames, Cubic reads QEMU’s firmware descriptor files (share/qemu/firmware/*.json, shipped by QEMU on Linux, Homebrew and Windows) and selects the plain UEFI (pflash) firmware whose target matches the VM’s architecture and machine (q35 for amd64, virt for arm64). Other special-purpose variants (such as secure boot) are skipped.

The firmware file named by the chosen descriptor is then resolved relative to the QEMU install (anchored on its share/ directory). This lets the firmware that ships next to QEMU resolve even when the descriptor records an absolute path that is not reachable, for example inside a confined snap, or in a relocated Windows build. On Linux the firmware and its descriptor ship in a separate package (ovmf / edk2, installed by the commands above). On macOS (Homebrew) and Windows they are bundled with QEMU.

Where the firmware comes from, per setup:

Setup	QEMU install prefix	Firmware file
Linux package manager	`/usr`	`/usr/share/OVMF/OVMF_CODE_4M.fd` (and distro equivalents)
snap (strict confinement)	`$SNAP/usr`	`$SNAP/usr/share/OVMF/OVMF_CODE_4M.fd`
macOS Homebrew / MacPorts	`/opt/homebrew`, `/usr/local`, `/opt/local`	`<prefix>/share/qemu/edk2-<arch>-code.fd`
Windows (winget)	`C:\Program Files\qemu`	`C:\Program Files\qemu\share\edk2-<arch>-code.fd`

Override

Point CUBIC_QEMU_DIR at a QEMU install and Cubic reads its firmware descriptors, or set the per-architecture CUBIC_QEMU_FW_AMD64 / CUBIC_QEMU_FW_ARM64 to use a specific firmware file directly:

$ CUBIC_QEMU_FW_AMD64=/opt/qemu/share/qemu/edk2-x86_64-code.fd cubic start my-vm

Environment Variable Reference

Variable	Tool	Description
`CUBIC_QEMU_DIR`	QEMU emulator, qemu-img and UEFI firmware	Directory of the QEMU install. Placed at the front of the search list for the binaries, and used to locate the `share/qemu/firmware` descriptors.
`CUBIC_QEMU_FW_AMD64`	UEFI firmware (amd64)	Path to a specific amd64 UEFI firmware (CODE) file. Overrides descriptor-based firmware selection for amd64 VMs.
`CUBIC_QEMU_FW_ARM64`	UEFI firmware (arm64)	Path to a specific arm64 UEFI firmware (CODE) file. Overrides descriptor-based firmware selection for arm64 VMs.