virt-manager

Resources

virt-manager is a lightweight GUI application designed for managing virtual machines and containers via the libvirt API.

It provides a comprehensive view of all domains (VMs and containers), displaying their current state (running or inactive), along with real-time performance data and resource utilization stats. Users can easily create and configure new domains, storage, and network interfaces, while also reallocating host resources between guest domains as needed.

Primarily tailored for managing KVM-based VMs, virt-manager also supports Xen and LXC containers. The interface presents an overview of live domain performance, as well as resource allocation metrics.

Domain creation and configuration are streamlined with intuitive wizards, allowing for fine-grained control over resource allocation and virtual hardware settings.

For hands-on management, virt-manager includes an embedded VNC and SPICE client, providing full graphical console access to guest domains.

Overview

First, virt-manager is a front-end to QEMU.
virt-manager can create/delete/maintain an instance of many virtual machine (VM).
virt-manager can start/stop a VM or a container.
virt-manager can mount a CD-ROM ISO image.
virt-manager can create different networking connections for the guest OS in VM to use.
virt-manager can create bridges, MACVLAN, static netdev, and NAT'd IP interface.
virt-manager can create/delete/maintain storage pools using many different filesystems such as directory, direct hard drive, gluster, iSCSI, LVM, multi-path devices, NetFS, SCSI, RADOS/Ceph, and Sheepdog.

virt-manager is a Python3 front-end script to both libvirt and QEMU main binary. Works on KDE and Gnome equally; also leverages gnome-keyring and kwalletcli for proper password storages.

The virt-manager main window looks like:

The domain window in detail mode looks like:

In console mode, the domain window looks like:

VM scopes

Each VM is a domain, when working with libvirt library and libvirt-client applications (ie., virsh, virt-manager).

Important
It is a domain instead of virtual machine (VM) because virt-manager/virsh/Libvirt refers to a container (LXC, Docker, Podman) or a virtual machine (QEMU, KVM, Xen, VirtualBox) depending on the environment, as well as its network profile, disk layouts, and available bare-metal resources: a domain.

Each domain can be in one of two different process ownerships and one of two different machine placements:

The process ownership available for a running domain are:

Session mode, User - Non-zero user ID
System mode, System daemon - root, UID=0

The machine placements are:

on a local host machine, on-premise
in a remote host machine, separated by network

Note
Libvirt terminology: The machine running libvirtd is a local host or a local hypervisor.

Note
The local hypervisor running inside another local hypervisor is a nested hypervisor. The domain running inside a local but nested hypervisor is the nested guest domain.

Privileges

Domain can run as the root or as the user's group ID matching the libvirt group name (or the wheel if no policykit package installed).

For a system-mode domain, the title bar of its detailed or console window does NOT show a "User session" phrase following its domain name and virtualization engine (QEMU/KVM) type.

For a session-mode domain, the title bar of its detailed or console window does show a "User session" after the domain name and virtualization engine (QEMU/KVM) type.

System mode

Domain can run in privileged (root) mode as a system daemon.

System domain is started after the init system initialization of host startup single-user/storage/network stages.

To run in system mode:

host$virt-manager --connect=qemu:///system

Session mode

A domain that runs in user-mode is a "User session" or a session mode.

To start a session-mode domain, a user must be given the libvirt group privilege (see also permissions in Libvirt).

Session-mode domain are started from the user-mode or from the display manager AutoStart script upon user login and after starting X/Wayland.

Session-mode domain runs in an unprivileged mode (not as root). If a user does not have the libvirt group in its supplementary group list, then use sudo start in root:

user $sudo virt-manager --connect qemu:///session

User with the libvirt group can start a domain in either system-mode or session-mode.

Machine placements

Each domain can run on an on-premise (local host, or sometimes a bare-metal) or can run in a cloud (remote host).

To run a domain, a hypervisor controller (libvirtd) must be up and running on a host machine, local or remote.

Note
A local host may be on a local physical server (on-premise) or inside another local hypervisor (guest host).

libvirtd must have their control socket opened before the virt-manager/virsh can manage the domain(s) on a host.

Control socket of a libvirtd are accessible by an UNIX domain socket (/var/run/libvirt/libvirt-sock) or by a inet socket (only for remote host) over TCP/IPv4 or TCP/IPv6 protocol.

Local domain placement

A hypervisor controller running on a local host controls the local domain.

To control the domain on a local host:

host$virt-manager --connect qemu:///session

Remote domain placement

The remote host system (aka cloud-based) are accessible by libvirt-based client (virt-manager, virsh).

To access the remote hypervisor controller by a TCP port number (default is 16509/tcp):

host$virt-manager --connect qemu+tcp://remote-host/system

Remote domain placement, by port #

To access the remote hypervisor controller by a non-default port number:

host$virt-manager --connect qemu+tcp://remote-host:<port>/system

To access securely the remote hypervisor controller using SSH protocol over tcp/22 port:

host$virt-manager --connect qemu+ssh://remote-host:<port>/system

Installation

BIOS/UEFI

Verify that the host hardware has the needed virtualization support, issue the following command:

host-root#grep --color -E "vmx|svm" /proc/cpuinfo

The vmx or svm CPU flag should be red highlighted and available.

And file /dev/kvm must exist as well:

host-root#ls /dev/kvm

/dev/kvm

If /dev/kvm does not exist, go back to QEMU for compliance.

USE flags

USE flags for app-emulation/virt-manager Desktop tool for managing libvirt virtual machines

`gui`	Enable support for a graphical user interface
`policykit`	Enable PolicyKit (polkit) authentication support
`sasl`	Enable connecting to SASL-enabled (e.g. Kerberos-protected) instances
`verify-sig`	Verify upstream signatures on distfiles

Data provided by the Gentoo Package Database · Last update: 2025-03-27 12:11 More information about USE flags

Note
If virt-manager is going to be used, be sure to enable the usbredir and spice USE flags on the qemu package for correct operation.

Emerge

root #emerge --ask app-emulation/virt-manager

Additional software

The virt-manager requires the app-emulation/libvirt package. See Libvirt — a virtualization management toolkit for installation.

Configuration

Environment variables

A list of optional environment variables that are read and checked by the virt-manager command:


Environment variable name	Description
`HOME`	path of home directory.
`DISPLAY`	the display X server and screen to which graphical applications should be sent.
`WAYLAND_DISPLAY`	the display Wayland server and screen to which graphical applications should be sent.
`LANG`	the default system locale and language settings.
`LANGUAGE`	the user's preferred language(s) for software localization, overriding the default language defined by $LANG
`GSETTINGS_BACKEND`	which backend is used for the GSettings system, which is part of the GNOME configuration system. Valid values are dconf and memory.
`GSETTINGS_SCHEMA_DIR`	the directory where GSettings schemas are located.
`SSH_ASKPASS_REQUIRE`	controls whether SSH uses an external program to prompt for a password when accessing a remote system. When set to yes, SSH will require a password prompt and will use the SSH_ASKPASS program to request the password. When set to no, it disables the password prompt, allowing for key-based authentication or other non-interactive methods. Example: SSH_ASKPASS_REQUIRE=yes ensures that an SSH password prompt will be shown when needed.

Environment variables - Test

VIRTINST_TEST_SUITE
VIRTINST_TEST_SUITE_FORCE_LIBOSINFO
VIRT_MANAGER_DEFAULT_FORK

Files

Whenever a domain starts, virt-manager checks for that domain XML file in each of the following paths:

System mode: /etc/libvirt/qemu/
User mode: $HOME/.config/libvirt/qemu/

The virt-manager command uses the following files:


Environment variable name	Description
HOME	path of home directory.
DISPLAY	the display X server and screen to which graphical applications should be sent.
$HOME/.config/libvirt/qemu/	Domain configs (user session)
$HOME/.config/libvirt/qemu/	Domain configs (user session)
/var/lib/libvirt/images/	Default VM disk image storage
/run/libvirt/ or /var/run/libvirt/	Runtime data (sockets, PIDs, state)
/usr/share/OVMF/, /usr/share/qemu/	Firmware for booting VMs
/etc/libvirt/qemu/networks/	Virtual network configs
/var/lib/libvirt/dnsmasq/	DHCP leases, runtime network info
/etc/libvirt/storage/	Storage pool metadata
etc/apparmor.d/ or /etc/selinux/	Security profiles (optional)
/var/run/libvirt/libvirt-sock	Control channel to hypervisor controller on local host
$HOME/.cache/virt-manager/virt-manager.log	Log file for user sessions
/proc/sys/kernel/cap_last_cap
/sys/devices/system/cpu/possible
/sys/devices/system/node/node0/meminfo
/sys/devices/system/node
$HOME/.cache/gstreamer-1.0/registry.x86_64.bin
$HOME/.config/dconf/user
$HOME/.config/gtk-3.0/colors.css
$HOME/.config/gtk-3.0/gtk.css
$HOME/.config/gtk-3.0/settings.ini
$HOME/.config/gtk-3.0/window_decorations.css
$HOME/.config/user-dirs.dirs
$HOME/.local/share/mime//mime.cache
/etc/libvirt/qemu/	Domain XML configs (system)

User permissions

To gain privilege in using virt-manager in user session mode, check for the libvirt group in user's supplementary group list:

host$id

uid=1000(jdoe) gid=1000(jdoe) groups=1000(jdoe),24(cdrom),25(floppy),27(sudo),29(audio),30(dip),44(video),46(plugdev),100(users),102(input),104(kvm),106(netdev),111(bluetooth),113(lpadmin),117(scanner),130(libvirt),131(wireshark),132(pipewire),993(ssh)

If libvirt is in the supplementary group, then virt-manager is ready for session (non-root) usage. Skip this subsection.

If libvirt is missing, complete the Group permission setup for Libvirt.

Autostart

Autostarting a domain can be done in session-mode or system-mode.

System-mode autostart

AutoStart for system-mode domain is natively supported by libvirtd.

For AutoStart option of a domain on power-up/reset:

from the virt-manager "Virtual Machine Manager" window, select the domain in the main panel, go to Edit->Virtual Machine Details menu suboptions,
or from the virt-manager "<domain> on QEMU/KVM" window, go to View->Detail menu options then select Boot Options line item in left navigation panel: under Autostart in main panel

Toggle the checkbox for "Start virtual machine at boot up".

Session-mode autostart

The hypervisor controller (libvirtd) does not support directly the autostart of session-mode --connect=qemu:///session) domains.

Because session mode runs as the unprivileged user, its libvirt instance is only available after a user logs in.

Also, libvirtd does not handle session mode.

The choices of auto-starting a session-mode domain are:

XDG AutoStart mechanism
Login script
X session script

XDG AutoStart mechanisms

Create a .desktop-type file in $HOME/.config/autostart/ directory.

host$vi $HOME/.config/autostart/libvirt-mydomain.desktop

Replace mydomain with the actual domain name.

Fill the .desktop file with:

FILE $HOME/.config/autostart/libvirt-mydomain.desktop"Typical .desktop file"

[Desktop Entry]
Name=My Domain VM
Type=Application
Exec=virsh --connect qemu:///session start mydomain
X-GNOME-Autostart-enabled=true

Replace mydomain with the actual domain name.

Tip
KDE Plasma will autostart ANY file in $HOME/.config/autostart/ directory, so no additional configuration setting is needed for KDE Plasma

For advance control of starting session-mode domains under KDE Plasma, select one of the following lines for your .desktop file:

FILE $HOME/.config/autostart/libvirt-mydomain.desktop.desktop file content

X-KDE-autostart-phase=0  # Pre-KDE startup
X-KDE-autostart-phase=1  # After KDE startup
X-KDE-autostart-phase=2  # After user apps

UNIX script

To autostart by UNIX login script, use one of the following login scripts:

$HOME/.bash_profile
$HOME/.profile.d/libvirt-autostart.sh

And insert the following command line into that login script:

CODE AutoStart domain via login script

virsh --connect qemu:///session start <vm-name>

Usage

The virt-manager can start domains in either system (root) or session (user) mode. For persistent domain operation, use system mode. For desktop session only (it goes away at logout), use session mode.

Important
Use --connect=qemu:///system if domain should start at bootup without any user desktop login. Use --connect=qemu:///session if only for the duration of a user's desktop session. Autostart option is available for both

For the session mode, run:

host$virt-manager

For the system-mode, add the --connect=qemu:///system option to virt-manager command.

host-platform$virt-manager --connect=qemu:///system

Connect types

virt-manager can connect to multiple local hosts and remote hosts using different protocols.

The types of connections to a hypervisor controller are:

qemu:// - local host UNIX domain socket to QEMU.
xen:// - local host Xen Domain 0 (Dom0)
qemu+ssh:// - a secured connection to QEMU over SSH/TCP protocol
xen+ssh:// - a secured connection to Xen Dom0 over SSH/TCP protocol

See URI in Libvirt for more breakdown details of Connect Type URI.

Starting

To start virt-manager:

host$virt-manager

To start virt-manager with the configuration window to gentoo guest host, using default QEMU UNIX socket connection:

host$virt-manager --connect qemu:///system --show-domain-editor gentoo

Note
Libvirt terminology: The domain running inside a local hypervisor is a guest host.

Starting domain

Domain can be started in:

virt-manager domain window, by clicking on Power On icon button with tip "Power on the virtual machine"
virt-manager domain window, by Virtual Machine->Run menu option
virt-manager main window, by selecting the domain in main panel under "QEMU/KVM User Session" group, then right-mouse context menu, then Run
by AutoStart init script executed by the display manager upon user login.

Note
Starting a display manager implies that system init initialization of local host single-user/storage/network stages are completed beforehand.

Shutting down

From the host platform:
- In virt-manager main menu bar using Virtual Machine -> Shutdown
From within the guest host:
- From the window manager, Start -> Shutdown icon

Invocation

user $virt-manager --help

usage: virt-manager [options]

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -c URI, --connect URI
                        Connect to hypervisor at URI
  --debug               Print debug output to stdout (implies --no-fork)
  --no-fork             Don't fork into background on startup
  --show-domain-creator
                        Show 'New VM' wizard
  --show-domain-editor NAME|ID|UUID
                        Show domain details window
  --show-domain-performance NAME|ID|UUID
                        Show domain performance window
  --show-domain-console NAME|ID|UUID
                        Show domain graphical console window
  --show-domain-delete NAME|ID|UUID
                        Show domain delete window
  --show-host-summary   Show connection details window

Also accepts standard GTK arguments like --g-fatal-warnings

Troubleshooting

virt-manager gui doesn't start or "virt-manager: command not found"

Version 4.1.0 changed USE flags, switching from gtk flag to gui. In order to (re)enable gui, the user must enable the gui flag before (re)build the package.

host-root#echo "app-emulation/virt-manager gui" >> /etc/portage/package.use/app-emulation

no polkit agent available to authenticate action 'org.libvirt.unix.manage'

This usually results from the user not being in the libvirt group. Add the user to the group with:

host-root#usermod -aG libvirt larry

QEMU/KVM not connected

Virt-manager uses libvirt as its backend to manage virtual machines. Therefore, the libvirt daemon needs to be started.

host-root#libvirtd

Or to start libvirtd at startup, add the daemon to the OpenRC runlevel / systemd target:

In OpenRC boot environment:

host-root#rc-update add libvirtd default

In SystemD boot environment:

host-root#systemctl enable libvirtd

'NoneType' object has no attribute 'conn'

This is typically a result in the cursor settings being misconfigured. The simplest fix is installing x11-themes/adwaita-icon-theme and updating gsettings to use the Adwaita cursor theme.

root #emerge --ask x11-themes/adwaita-icon-theme

host$gsettings set org.gnome.desktop.interface cursor-theme "Adwaita"

Removal

root #emerge --ask --depclean --verbose app-emulation/virt-manager