Linuxinfrastructure

Proxmox GPU passthrough preflight

Run one read-only report before GPU passthrough to verify IOMMU, enumerate groups, and show the driver currently owning each display device.

Distrosproxmox
Shellbash
Updated
Script
bash
#!/usr/bin/env bash
# Read-only Proxmox PCI-passthrough preflight. Run as root on the node.
set -u

if [ "${EUID:-$(id -u)}" -ne 0 ]; then
  printf '%s\n' 'ERROR: run this report as root so dmesg is readable.' >&2
  exit 1
fi

if ! command -v lspci >/dev/null 2>&1; then
  printf '%s\n' 'ERROR: lspci is missing. Install the pciutils package first.' >&2
  exit 1
fi

printf '%s\n' '=== Active kernel command line ==='
cat /proc/cmdline

printf '\n%s\n' '=== IOMMU messages ==='
dmesg | grep -Ei 'DMAR|IOMMU|AMD-Vi' || printf '%s\n' 'No IOMMU messages found.'

printf '\n%s\n' '=== Display and audio functions ==='
lspci -nnk | grep -A3 -Ei 'VGA|3D|Display|Audio' || true

printf '\n%s\n' '=== IOMMU groups ==='
if [ ! -d /sys/kernel/iommu_groups ]; then
  printf '%s\n' 'ERROR: /sys/kernel/iommu_groups does not exist.' >&2
  exit 1
fi

group_count=$(find /sys/kernel/iommu_groups -mindepth 1 -maxdepth 1 -type d | wc -l)
case "$group_count" in
  ''|*[!0-9]*)
    printf '%s\n' 'ERROR: group count was not a number.' >&2
    exit 1
    ;;
  0)
    printf '%s\n' 'ERROR: IOMMU group directory is empty.' >&2
    exit 1
    ;;
esac

printf 'Found %s IOMMU groups.\n' "$group_count"
for group_dir in /sys/kernel/iommu_groups/*; do
  group=${group_dir##*/}
  for device in "$group_dir"/devices/*; do
    address=${device##*/}
    printf 'Group %-4s ' "$group"
    lspci -nns "$address"
  done
done | sort -V

printf '\n%s\n' 'PASS: IOMMU groups exist. Inspect the target GPU group manually.'

What this does

This script gathers the evidence I want before assigning a GPU to a Proxmox VM: the active kernel command line, IOMMU messages, display and audio functions with their current drivers, and every IOMMU group. It changes nothing.

The report deliberately stops short of declaring a GPU safe. Linux treats the whole IOMMU group as the isolation unit, so a person still needs to confirm that the target group contains only functions they intend to give to one guest.

Prerequisites

  • Run it as root in the shell of the Proxmox node that physically contains the GPU.
  • Install pciutils if lspci is unavailable.
  • Enable Intel VT-d or AMD IOMMU in the motherboard firmware first.
  • Keep physical or out-of-band console access before changing the host’s only display adapter.

Notes

  • Make these values your own: this playbook has no VM ID or PCI address to replace. Its output supplies the real addresses for your host. If a value in the companion guide looks specific to one machine, it is a placeholder to change—not a literal to copy.
  • A non-zero group count proves the kernel exposed IOMMU groups; it does not prove the target group is safe.
  • A graphics card often has separate display and audio functions. Read every line in its group before enabling Proxmox’s All Functions option.
  • If the group also contains an unrelated network or storage controller, try another physical slot or a firmware update. Do not begin with an ACS override that weakens the visible isolation boundary.
  • tested: false is intentional: the script is syntax-checked and read-only, but this publication run did not execute it on a GPU-equipped Proxmox host.

Walk through the handoff and workload tests in Proxmox GPU passthrough: give one VM the whole card.

All playbooks