virt-viewer

Launch virt-viewer with a prompt to select running virtual machines

$ virt-viewer

$ virt-viewer "[domain]"

$ virt-viewer --reconnect --wait "[domain]"

$ virt-viewer --connect "xen//[url]" "[domain]"

$ virt-viewer --connect "qemu+ssh//[username]@[url]/system" "[domain]"

virt-viewer [OPTIONS] <domain>
virt-viewer [OPTIONS] --connect URI <domain>
virt-viewer [OPTIONS] --direct <SPICE|VNC>://HOST:PORT

<domain>
    Specifies the virtual machine by its name or UUID when connecting via libvirt.

--connect URI
    Connects to a specific hypervisor URI (e.g., qemu:///system, xen:///). Defaults to the system default if not specified.

--direct URI
    Connects directly to a graphics server URI (e.g., spice://localhost:5900 or vnc://remotehost:5901) without involving libvirt.

--full-screen
    Starts the viewer in full-screen mode. Can be toggled with F11 (or Shift+F11).

--auto-resize
    Enables automatic resizing of the guest display to fit the window size (requires SPICE guest tools).

--no-cursor-restraint
    Disables the automatic grabbing of the mouse cursor when the viewer window is focused.

--spice
    Forces the viewer to use the SPICE protocol. If not specified, the protocol is auto-detected or defaults to SPICE if available.

--vnc
    Forces the viewer to use the VNC protocol.

--debug
    Enables verbose debugging output for troubleshooting.

-h, --help
    Displays a short help message and exits.

-V, --version
    Displays the version information and exits.

virt-viewer is a lightweight graphical viewer for virtual machines managed by the libvirt virtualization management library. It provides a simple yet powerful interface to interact with the guest operating system's console, supporting both the SPICE and VNC display protocols. While virt-viewer can connect directly to a graphics server using a URI, its primary strength lies in its tight integration with libvirt. This integration allows users to easily connect to virtual machines by their domain name or UUID, letting libvirt handle the underlying connection details. It's an essential component for users needing direct visual access to their QEMU/KVM, Xen, or other libvirt-managed virtual machines, offering features like full-screen mode, automatic guest display resizing, and, with proper guest agents, clipboard sharing and USB device redirection.

For optimal performance and features like clipboard sharing and USB redirection, it's highly recommended to install the respective SPICE guest tools (for SPICE connections) or equivalent VNC guest agents within the virtual machine. Without them, some advanced features might be unavailable or have limited functionality. Direct connections using --direct bypass libvirt's management and might not offer the same level of integration and features as connections managed by libvirt.

virt-viewer supports both SPICE (Simple Protocol for Independent Computing Environments) and VNC (Virtual Network Computing). SPICE is generally preferred for its richer feature set, including better video playback, audio support, clipboard sharing, and USB device redirection, making it ideal for desktop-like experiences. VNC is a more generic and widely compatible protocol, often used when SPICE is not available or desired.

One of virt-viewer's key strengths is its tight integration with libvirt. When connecting to a domain (VM) via libvirt, virt-viewer leverages libvirt's APIs to discover the VM's display details (protocol, port, address), simplifying the connection process. This means you don't need to manually specify IP addresses or ports for VMs managed by libvirt; just the domain name or UUID is sufficient.

Beyond simply displaying the console, virt-viewer allows full keyboard and mouse interaction with the guest OS. Features like full-screen mode (toggle with F11), automatic guest display resizing (with SPICE guest tools), and clipboard synchronization greatly enhance the user experience. It also provides options for USB device redirection, enabling the host's USB devices to be passed through to the virtual machine, which is crucial for tasks requiring hardware access.

virt-viewer is an integral part of the virt-manager project, which is primarily developed by Red Hat. It emerged as a dedicated and optimized tool for viewing virtual machine consoles, specifically designed to work seamlessly within the libvirt ecosystem. Prior to dedicated tools like virt-viewer, users often relied on generic VNC clients. virt-viewer improved upon this by offering deeper integration with libvirt's capabilities, enabling automatic discovery of VM display details, better handling of protocols like SPICE, and enhanced features over generic viewers. Its development reflects the continuous effort to provide robust and user-friendly tools for Linux virtualization.

virt-manager(1), virsh(1), virt-install(1), qemu-system-x86_64(1), libvirt(3)