GPUs

Commands for inspecting the host's GPUs and seeing which virtual machines are using them. GPUs are treated as a host resource: the daemon enumerates the PCI display controllers present on the machine and cross-references every libvirt domain to determine which GPUs are currently claimed by a VM.

GPUs attached out-of-band (for example, a VM created directly by TrueNAS against libvirt) are detected the same way as VMs the daemon created — the information is read from each domain's hostdev definition.

ls

List the host's GPUs, showing the PCI address, device name, bound kernel driver, IOMMU group, and whether the GPU is currently in use (and by which VM).

vmr gpu ls

Options

Option	Description
-q, --names-only	Print only PCI addresses, one per line (useful for scripting/completions). Host display GPUs are omitted, since they can't be passed through.

Output Fields

Field	Description
PCI ADDRESS	The GPU's PCI address in DDDD:BB:SS.F form (e.g. 0000:01:00.0)
DEVICE	Vendor and product name resolved from libvirt node-device info
DRIVER	Kernel driver bound to the device (e.g. vfio-pci, nvidia)
IOMMU	IOMMU group number, or - if unknown
STATUS	What is holding the GPU — see below. Color-coded in a terminal.

Status values

The statuses are checked in priority order (host GPU > in use > assigned > available), so a GPU shows only its most significant state.

Value	Color	Meaning
host GPU	red	The host's primary display GPU (sysfs boot_vga). It drives the host console and cannot be passed through.
in use (<vm>)	green	A running VM currently holds the GPU.
assigned (<vm>,...)	yellow	Configured on one or more stopped VMs. A GPU may be assigned to many VMs, but only one can run with it at a time.
available	—	Not a host GPU and not claimed by any VM. Check the DRIVER column for passthrough readiness: vfio-pci (or no driver) is ready; a host driver such as amdgpu or nvidia means it's currently bound to the host.

Examples

vmr gpu ls

# Just the PCI addresses, for scripting
vmr gpu ls -q

IOMMU groups

A GPU rarely sits alone in its IOMMU group — its companion audio function and sometimes a PCI bridge share the group, and all members must be passed through together. The IOMMU column lets you spot devices that belong to the same group.

Attaching a GPU to a VM

GPUs are a host-specific runtime choice — PCI addresses differ from machine to machine — so they are never baked into an image. An image only declares the graphics family it supports; the actual device is chosen when you run the VM.

Wherever you reference a GPU, the reference is either a PCI address (0000:01:00.0) or a case-insensitive substring of the device name (nvidia, a4000); a name reference must match exactly one host GPU. The daemon then attaches the whole IOMMU group of the matched GPU (so the companion audio function and any bridge come along) with managed='yes', so libvirt binds the devices to vfio-pci on launch and restores them on shutdown.

Declaring graphics support on an image

An image advertises the graphics family it supports — typically the vendor whose drivers are installed in the guest — with the graphicsmetadata label in its VMFile:

metadata:
  name: ml/trainer
  labels:
    graphics: nvidia
spec:
  resources:
    cpu: 8
    memory: 16GiB
    bootloader:
      type: UEFI

This label is purely declarative — it attaches nothing on its own. When you later attach a GPU with --gpu, the daemon compares the chosen GPU's vendor against the label and prints a warning (it does not fail) if they don't match, e.g. attaching an AMD card to an image labelled graphics: nvidia.

Attaching at run time with --gpu

Pass --gpu to vmr run to attach a GPU when launching a VM. It is repeatable:

vmr run myuser/my-vm:latest --gpu 0000:01:00.0
vmr run myuser/my-vm:latest --gpu nvidia --gpu 0000:02:00.0

To change the GPUs of an existing VM, use vmr edit --gpu (the new set replaces the old and applies on the VM's next boot). In a compose project, list GPUs per service with the gpus field.

Attached GPUs show up in vmr describe <vm> and the owning VM appears in the STATUS column of vmr gpu ls.