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, and also its network profile, disk layouts, and any bare-metal resources: a domain.

Each domain can be in different process ownership and different machine placement:

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

Important
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).

Tip
See Libvirt permissions on setting a user privilege

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.

Tip
If the virt-manager title bar does not say "User session", then the domain is in system mode.

System mode

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

On the host, 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:

host$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-04-26 12:47 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

AutoStart feature enables a domain to power up automatically after the host or X session gets ready.

See AutoStart in Libvirt for autostart features.

Service

To check if the hypervisor controller (libvirtd) is up, run:

host$virsh list --all

If it works and lists the domains (or "no domains defined"), the daemon is running.

If it errors like:

   error: failed to connect to the hypervisor

then the daemon is likely down or you're not using the right URI.

Usage

A hypervisor (local or remote) must be up and running before virt-manager can start controlling a domain. See Libvirt service on starting an hypervisor.

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

Connect types

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

The syntax of the URI is:

   hypervisor+transport://[user@]hostname[:port][/path]
   hypervisor+transport:///path

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 options
virt-manager main window, by selecting a domain in the main panel under "QEMU/KVM User Session" group, then right-mouse context menu, then Run
by the AutoStart init script executed by 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

Removal

Removal of app-emulation/libvirt package (toolkit, library, and utilities) can be done by executing:

root #emerge --ask --depclean --verbose app-emulation/libvirt

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"

Missing default network

If you accidentally deleted the 'default' network in virt-manager, to restore default network using:

virt-manager
virsh

On some system, the default.xml can be found in /usr/share/libvirt/networks/default.xml. If not, create a new default.xml XML file for the default network:

FILE /etc/libvirt/qemu/networks/default.xml

<network>
  <name>default</name>
  <uuid>REPLACE-WITH-NEW-UUID</uuid>
  <forward mode='nat'/>
  <bridge name='virbr0' stp='on' delay='0'/>
  <ip address='192.168.122.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.122.2' end='192.168.122.254'/>
    </dhcp>
  </ip>
</network>

Within virt-manager

Go to main dialog of virt-manager:

Select the QEMU/KVM group item in main window.

Note
Do not select the virtual machine itself.

At the menubar, select Edit, then Connection details. A new Connection details dialog box appears.

Select Virtual connections tab.

In left navigation window, at the bottom, press the add ('+') button. A 3rd dialog window titled Create a new virtual network appears.

Select the XML group tab.

Paste the content of default.xml given above. UUID will automatically be filled in.

Using virsh

Or you can use virsh directly:

You can generate a UUID using the command:

root #uuidgen

Insert the UUID into the default.xml file:

root #virsh net-define /usr/share/libvirt/networks/default.xml

Set auto-start to enable:

root #virsh net-autostart default

Start the default network:

root #virsh net-start default

Confirm default network exist

To confirm the network is active

{{RootCmd|virsh net-list --all||collapse-output=true|output=

 Name      State    Autostart   Persistent
--------------------------------------------
 default   active   yes         yes