virt-manager

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, and manage multiple virtual machines (VMs).
• 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).

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

The process ownership available for a running domain are:

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

The machine placements are:

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

virt-manager stack

virt-manager is a Python GTK frontend. It does not virtualize itself. It only interface with Libvirt.

For the primary hypervisor part of the virt-manager stack, it communicates with libvirtd daemon, and evokes QEMU (ie., qemu-system-x86_64).

For the front-end part, virt-manager GUI, using Libvirt API, evokes virsh, virt-install, and virt-viewer.

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 domain, the window title bar does NOT show this "User session" phrase following its domain name and virtualization engine (QEMU/KVM) type, in either detailed or console view mode.

Virt-manager-titlebar-system.png

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

Virt-manager-titlebar-session.png

System connection

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 through a system connection:

Session connection

A domain that runs in per-user mode is a "User session" or session connection, or simply, a session.

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

Session domain are started from the user CLI or from the display manager AutoStart script upon user login and after starting X11 or Wayland window manager.

Session 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:

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.

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:

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):

Remote domain placement, by port #

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

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

Installation

BIOS/UEFI

Verify that the host hardware has the required virtualization support by running the following command:

The vmx (Intel VT-x) or svm (AMD-V) CPU flag should be highlighted in red if present.

Also ensure that the /dev/kvm device node exists:

/dev/kvm

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

USE flags

Emerge

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:

For additional environment variables used by commands evoked by virt-manager, see virsh, libvirt, QEMU or consult its man-page.

Testing / Internal Use Environment Variables

These are primarily used during unit testing, automated CI runs, or manual debugging of virt-manager, virt-install, or related libvirt bindings.

Files

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

• System connection: /etc/libvirt/qemu/ via qemu:///system.
• Session (per-user) connection: $HOME/.config/libvirt/qemu/ via qemu:///session.

Libvirt

For virt-manager, files are organized as:

• /etc/libvirt/ -> definitions (XML)
• /var/lib/libvirt/ -> persistent VM state (disks, nvram)
• /run/libvirt/ -> runtime execution state
• /var/log/libvirt/ -> logs

System connection (qemu:///system)

Session connection (qemu:///session)

Storage Pool

User-defined storage pools are an alternative to images/ directory.

Libvirt can define arbitrary storage pools, for example:

 /srv/vm-storage/
 ~/vm-disks/

Defined via:

 virsh pool-define
 virsh pool-start

These are independent of /var/lib/libvirt/images/.

Networking

virt-manager supports the following network types:

User permissions

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

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:

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) connection mode. For persistent domain operation, use system. For desktop session only (it goes away at logout), use session.

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:

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

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.

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

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:

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.

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:

QEMU/KVM not connected

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

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

In OpenRC boot environment:

In SystemD boot environment:

'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.

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:

<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: virt-manager main window

Select the QEMU/KVM group item in main window.

At the menubar, select Edit, then Connection details.

* QEMU/KVM (system instance)
* QEMU/KVM User session (session instance)

* network definitions
* storage pools
* device visibility
* VM inventories

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:

Insert the UUID into the default.xml file:

Set auto-start to enable:

Start the default network:

Confirm default network exist

To confirm the network is active

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

See also

• Libvirt/domain — represents a virtualized guest instance, such as a virtual machine, container, or other supported environment.
• Virtualization — the concept and technique that permits running software in an environment separate from a computer operating system.
• QEMU — a generic, open-source hardware emulator and virtualization suite.
• QEMU/Front-ends — provide graphical, terminal, web-based, or command-line interfaces for configuring, managing, or accessing QEMU virtual machines.

• Libvirt — a virtualization management toolkit
• Libvirt/QEMU_networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
• Libvirt/QEMU_guest — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.

• Virt-manager/QEMU_guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.

• QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• GPU passthrough with virt-manager, QEMU, and KVM — directly present an internal PCI GPU as-is for direct use by a virtual machine
• Virsh — a CLI-based virtualization management toolkit

• Virt-manager
• QEMU
• Virtualization
• GUI software
• Libvirt