QEMU

QEMU (Quick EMUlator) is a generic, open-source hardware emulator and virtualization suite.

Introduction

QEMU is a Type-2 hypervisor, which runs within user namespace on a host platform and performs virtual hardware emulation. Inside a virtual machine, QEMU can emulate multiple operating systems; it can also emulate embedded systems.

QEMU supports more than 32 CPU architectures. It emulates nearly all the opcodes of these CPUs, and can execute multiple virtual CPUs in parallel.

QEMU can be paired with KVM to run VMs at near-native speed. This is accomplished by using hardware extensions such as Intel VT-x or AMD-V. It can then emulate user-level processes, which allow applications, compiled for one architecture, to run on a different one.

When used in conjunction with an accelerator plugin, QEMU becomes a Type-1 hypervisor, which runs in kernel namespace. This allows a user namespace program access to the hardware virtualization features of various processors. Such an accelerator can be KVM (Kernel-based Virtual Machine) or Xen.

If no accelerator is used, QEMU will run entirely in user namespace, using its built-in binary translator, TCG (Tiny Code Generator). Using QEMU without an accelerator is relatively inefficient and slow. The table at the end of this section lists available accelerators.

QEMU has different operating modes. System mode emulates a full system, including processors and peripherals, which allows running different operating systems and configure hardware configurations. User mode emulates a specific CPU architecture, which allows running Linux binaries that have been compiled for a different instruction set architecture.

QEMU virtual machines (VMs) can interface with many types of physical host hardware, including CD-ROM drives, USB devices, audio interfaces, hard disks and network cards.

By default, QEMU defaults to using the qcow2 virtual disk image format. This format only uses as much host disk space as the guest OS grows to use. Using the snapshot method, the guest OS can revert back to its desired state in time.

QEMU can save and restore the state of VMs of all its running programs.

QEMU does not depend on graphical output methods on the host system. Instead, it makes use of an integrated VNC server to access the screen of the guest OS.

A number of plugins are available for QEMU, including several accelerator plug-ins:

The following pages provide detailed instructions related to QEMU configuration and options:

• QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• QEMU/Networking/Bridge with Wifi Routing
• QEMU/Networking/KVM IPv6 Support — describes IPv6 support in QEMU/KVM.
• QEMU/Networking/Open vSwitch network
• QEMU/Options — describes some of the options useful for configuring QEMU virtual machines (VMs).
• QEMU/OS2WarpV3 guest
• QEMU/Windows guest — setup of a Windows guest using QEMU

• Virtiofs — a shared file system that lets virtual machines access a directory tree on the host

Installation

BIOS and UEFI firmware

In order to utilize KVM, either Intel's Vt-x (vmx) or AMD's AMD-V (svm) must be supported by the processor. These technologies permit multiple operating systems to concurrently execute operations on processors.

To inspect hardware for virtualization support, run:

If KVM support is available, there should be a kvm device at /dev/kvm. This will take effect after the system has booted to a KVM-enabled kernel.

Kernel

Described below are the basic requirements for KVM kernel configuration for the host OS. A more complete and up-to-date list can be found at the KVM Tuning Kernel page.

General setup --->
 Timers subsystem --->
 [*] High Resolution Timer Support Search for <code>CONFIG_HIGH_RES_TIMERS</code> to find this item.

Physical CPU processor support - Host

If KVM support is not available, insert CONFIG_KVM=y into the /usr/src/linux/.config and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host is rebooted.

[*] Virtualization Search for <code>CONFIG_CONFIG_VIRTUALIZATION</code> to find this item. --->
 <*> Kernel-based Virtual Machine (KVM) support Search for <code>CONFIG_CONFIG_KVM</code> to find this item.

Processor support

[*] Virtualization Search for <code>CONFIG_CONFIG_VIRTUALIZATION</code> to find this item. --->
 <M> KVM for Intel processors support Search for <code>CONFIG_CONFIG_KVM_INTEL</code> to find this item.

[*] Virtualization Search for <code>CONFIG_CONFIG_VIRTUALIZATION</code> to find this item. --->
 <M> KVM for AMD processors support Search for <code>CONFIG_CONFIG_KVM_AMD</code> to find this item.

Handling kernel config at CLI

To set the various kernel configuration settings from the command lines, the linux/scripts/kconfig/merge_config.sh shall be used here:

Mandatory kernel configuration options to set:

CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y

utility

Useful kernel configuration options to use:

CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMERS=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y

Networking

Accelerated networking, required for vhost-net USE flag (recommended):

Device Drivers --->
 [*] VHOST drivers --->
 <*> Host kernel accelerator for virtio net Search for <code>CONFIG_CONFIG_VHOST_NET</code> to find this item.

Device Drivers --->
 [*] Network device support Search for <code>CONFIG_CONFIG_NETDEVICES</code> to find this item. --->
 [*] Network core driver support Search for <code>CONFIG_CONFIG_NET_CORE</code> to find this item.
 <*> Universal TUN/TAP device driver support Search for <code>CONFIG_CONFIG_TUN</code> to find this item.

802.1d Ethernet bridging

Needed for 802.1d Ethernet bridging:

[*] Networking support Search for <code>CONFIG_CONFIG_NET</code> to find this item. --->
 Networking options --->
 <*> The IPv6 protocol Search for <code>CONFIG_CONFIG_IPV6</code> to find this item.
 <*> 802.1d Ethernet Bridging Search for <code>CONFIG_CONFIG_BRIDGE</code> to find this item.

Intel VT-g (integrated graphics adapter virtualization)

Mediated device passthrough for Intel GPUs (Broadwell to Comet Lake)^[4]

Device Drivers --->
 <*> VFIO Non-Privileged userspace driver framework
 <*> Mediated device driver framework
 Graphics Support --->
 <*> Intel 8xx/9xx/G3x/G4x/HD Graphics
 [*] Enable Intel GVT-g graphics virtualization host support
 <*> Enable KVM host support Intel GVT-g graphics virtualization

USE flags

Some packages have a qemu USE flag, to enable QEMU support.

The USE flags for QEMU itself are:

USE_EXPAND

Additional ebuild configuration is provided by the USE_EXPAND variables QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS. The USE flags for app-emulation/qemu (as shown by e.g. equery from app-portage/gentoolkit )include all the available targets. Most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything, which is probably fine for most users.

For each target specified, a qemu executable will be built. A softmmu target is the standard QEMU use-case of emulating an entire system, like VirtualBox or VMware, but with optional support for emulating CPU hardware along with peripherals. user targets execute user-mode code only; the (somewhat ambitious) purpose of these targets is to "magically" allow importing user namespace Linux ELF binaries from a different architecture into the native system (like multilib, without the need for a software stack or a CPU capable of running it).

In order to enable QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS, add the following to /etc/portage/package.use :

app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64

Emerge

After reviewing and adding any desired USE flags, emerge app-emulation/qemu :

Additional software

To connect to the SPICE server of QEMU, a GUI client like net-misc/spice-gtk is required.

Configuration

The following sub-articles provide detailed instructions on QEMU configurations and options:

• QEMU/Options — describes some of the options useful for configuring QEMU virtual machines (VMs).
• QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• QEMU/Windows guest — setup of a Windows guest using QEMU
• QEMU/OS2WarpV3 guest

Environment variables

Files

QEMU uses the following files and directories for configuration:

• /etc/libvirt/qemu.conf - QEMU configuration file.
• /etc/libvirt/qemu-lockd.conf - QEMU lock files
• /etc/libvirt/qemu-sanlock.conf - QEMU SAN lock
• /etc/libvirt/qemu/<domain-name>.xml - Domain XML setting for a virtual machine or container.
• /etc/libvirt/qemu/autostart/<domain-name>.xml - Autostart this domain (virtual machine or container).
• /etc/libvirt/qemu/networks/<network-name>.xml - Network XML setting file for a network connection
• /etc/libvirt/qemu/networks/autostart/<network-name>.xml - Autostart this network connection.
• /var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file> - UNIX socket file for Libvertd daemon API
• /var/cache/libvirt/qemu/capabilities/<hash-value>.xml - Host OS capabilities in XML format
• /var/lib/libvirt/qemu/checkpoint/
• /var/lib/libvirt/qemu/<domain-9-XXXX>/ - holds UNIX sockets and AES keys for this domain.
• /var/lib/libvirt/qemu/dump/
• /var/lib/libvirt/qemu/nvram/
• /var/lib/libvirt/qemu/ram/
• /var/lib/libvirt/qemu/save/ - holding directory of hibernation images
• /var/lib/libvirt/qemu/snapshot/ - holding directory of snapshots
• /var/run/libvirt/qemu - various UNIX socket and PID files for the libvirtd daemon.

Usage

Todo:

• This section needs a few basic examples, prior to the "Starting QEMU with a VNC server" subsection, of invoking a QEMU binary (including running it with a Live CD and no disk image).

QEMU can be used from the command line or via a GUI front-end. For information about available front-ends, refer to QEMU/Front-ends.

Permissions

In order to run a KVM-accelerated virtual machine without root privileges, one can add normal users to the kvm group:

Disk image formats

QEMU supports the following disk image formats:

• QEMU copy-on-write: .qcow2, .qed, .qcow, .cow
• VirtualBox Virtual Disk Image: .vdi
• CD/DVD (ISO-9660) images: .iso
• Raw images, that guest OS can control: .img
• VFAT-16
• VMware Virtual Machine Disk: .vmdk
• Virtual PC Virtual Hard Disk: .vhd
• Parallels disk image (read-only): .hdd, .hds
• Apple macOS Universal Disk Image Format (read-only): .dmg
• Bochs (read-only)
• Hyper-V Virtual Hard Disk: .vhdx
• Linux cloop (read-only)
• LUKS disk images

See qemu-img for more disk image information.

Creating a disk image

To create a 4 GiB raw disk image:

Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296

total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img

To create a raw disk image with copy-on-write (COW) disabled:

Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on

total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img

The nocow option is also a file attribute, which can be determined via the command lsattr(1) ^[5] .

The following will create a qcow2 disk image (useful if the host filesystem does not support sparse files):

Formatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16

total 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2

Preparing a bootable disk image from scratch

A system can be copied onto a disk image without using a CD-ROM installation medium.

By default, QEMU uses BIOS firmware to boot the system.

The disk image can be prepared with an msdos disk label and a gap between the end of the 512 byte MBR (Master Boot Record) and the start of the first partition. The gap is needed for boot loaders like GRUB, which place boot code within this gap.

The following example uses the raw disk image created above.

A raw disk image can be prepared by attaching it as a loop device:

/dev/loop0

• The --find option finds the first unused loop device.
• The --partscan option forces the Linux kernel to scan the partition table on the newly created loop device, where a default sector size of 512 bytes is assumed.
• The --show option displays the name of the assigned loop device, when the --find option is used.

Attached loop devices can be listed with the following command:

NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512

The loop device can then be formatted like a normal disk.

To print the partition table, use parted(8) :

Error: /dev/loop0: unrecognised disk label
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: unknown
...

Next, create a new partition table with an msdos disk label:

Information: You may need to update /etc/fstab.

The returned information can be ignored, since an entry in the configuration file /etc/fstab is not needed.

parted now indicates that the partition table is msdos:

Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
...

Next, create an ext4 partition with an offset of 2 MiB:

The value of -1 represents the last sector of the partition.

To check that the first partition has been successfully created:

Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
 
Number Start End Size Type File system Flags
 1 2.00MiB 4095MiB 4093MiB primary

This will also attach a new loop device at /dev/loop0p1:

brw-rw---- 1 root disk 7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1

Set the boot flag:

All partition flags can be found in the "Flags" column:

Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
 
Number Start End Size Type File system Flags
 1 2.00MiB 4095MiB 4093MiB primary boot

Create the ext4 filesystem declared via parted earlier:

mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
 32768, 98304, 163840, 229376, 294912, 819200, 884736
 
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done

Mount it at /mnt:

Filesystem Type Size Used Avail Use% Mounted on
/dev/loop0p1 ext4 3.9G 24K 3.7G 1% /mnt

Create the /mnt/boot/grub directory, which will be used by GRUB later:

mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'

Install GRUB on the loop device, instructing it to install its files to /mnt/boot/grub/:

/mnt/boot/grub/
├── fonts/
│   └── unicode.pf2
├── grubenv
├── i386-pc/
│   ├── acpi.mod
│   ├── adler32.mod
│   ├── affs.mod
│   ├── afs.mod
│   ├── afsplitter.mod
│   ├── ahci.mod
│   ├── all_video.mod
│   ├── aout.mod
│   ├── archelp.mod
│   ├── ata.mod
[...]

Unmount the filesystem and detach the loop device:

If the loop device is still busy - for example, processes are still accessing /mnt/ - no error will be returned. This can be verified and solved with the following commands:

NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512

sleep 31813 root cwd DIR 259,0 4096 131074 /mnt/boot/grub

This is sufficient to boot into a GRUB boot prompt.

This setup can be used as the basis for a bootable system.

CPU selection

QEMU supports around 34 different CPU architectures. To list those available:

/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx
/usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x
/usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4
/usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb
/usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc
/usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64
/usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore
/usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64
/usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm
/usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa
/usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb

To get a list of CPUs for a specific architecture, use the -cpu help option with the binary for that architecture, e.g.:

Available CPUs:
 486 (alias configured by machine type)
 486-v1 
 Broadwell (alias configured by machine type)
 Broadwell-IBRS (alias of Broadwell-v3)
 Broadwell-noTSX (alias of Broadwell-v2)
...

As noted in the introduction, QEMU CPUs can have additional support for accelerators. An accelerator can usually only accelerate the features available on the host CPU, so the selection of CPU affects performance.

To list available accelerators, pass the -accel help option to the relevant binary, e.g.:

Accelerators supported in QEMU binary:
tcg
mshv
kvm

Starting QEMU with a VNC server

To start QEMU with a VNC server listening on a local UNIX socket:

A CD-ROM can be added by using the -cdrom option, e.g. -cdrom <image>, where <image> should be replaced with the name of an ISO image.

Connecting to a QEMU VNC server

Any VNC viewer can be used to connect to the VNC server, e.g. vncviewer, provided by net-misc/tigervnc :

TigerVNC viewer v1.15.0
Built on: 2025年05月13日 12:30
Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.
 
Tue May 13 14:44:36 2025
 DecodeManager: Detected 4 CPU core(s)
 DecodeManager: Creating 4 decoder thread(s)
 CConn: Connected to socket /run/user/1000/qemu-vnc.sock
 CConnection: Server supports RFB protocol version 3.8
 CConnection: Using RFB protocol version 3.8
 CConnection: Choosing security type None(1)
 CConn: Using pixel format depth 24 (32bpp) little-endian rgb888
 CConn: SetDesktopSize failed: 3

This will open a separate window with the display output of the QEMU VM:

Qemu minimal vm with grub2.png

Troubleshooting

Refer to QEMU/troubleshooting.

Removal

Unmerge

See also

QEMU

• qemu-img — a QEMU disk image utility
• QEMU/Front-ends — provide graphical, terminal, web-based, or command-line interfaces for configuring, managing, or accessing QEMU virtual machines.
• QEMU/Guest/Gentoo Linux — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• QEMU/Networking/Bridge with Wifi Routing
• QEMU/Networking/KVM IPv6 Support — describes IPv6 support in QEMU/KVM.
• QEMU/Networking/Open vSwitch network
• Category:QEMU Guests

libvirt and virt-manager

• libvirt — a virtualization management toolkit
• libvirt/QEMU guest — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.
• libvirt/QEMU networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
• virt-manager — lightweight GUI application designed for managing virtual machines and containers via the libvirt API.
• virt-manager/QEMU guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.
• GPU passthrough with virt-manager, QEMU, and KVM — directly present an internal PCI GPU as-is for direct use by a virtual machine

General

• Comparison of virtual machines — compares the features of several platform virtual machines.
• Fast Virtio VM — explains a way to build a blazing fast Gentoo VM under KVM using Virtio and mdev.
• Remote desktop — a guide to remote desktop software on Gentoo
• Virtualization — the concept and technique that permits running software in an environment separate from a computer operating system.

External resources

• https://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
• https://wiki.qemu.org/Main_Page - The Official QEMU wiki

References

• Pages using duplicate arguments in template calls
• Outdated articles
• Todo articles
• Virtualization
• QEMU
• Emulation