Skip to main content
RunBook Academy

Proxmox VEIX · Virtual MachinesPassthrough

PCI/GPU passthrough, TPM, UEFI

Advanced⏱ ~18 min

What you'll learn

  • Enable IOMMU and configure VFIO
  • Pass through a GPU or NVMe controller to a VM
  • Configure TPM 2.0 and Secure Boot
  • Troubleshoot common passthrough issues

Prerequisites

Verified against Proxmox VE 9.2.4 · Proxmox Backup Server 4.2.5 · Ceph Squid / Tentacle · Debian 13 (Trixie) · Linux kernel 7.0 (PVE 9.2 default) · 2026-08-07

Not yet marked complete on this device.

Why this matters in production

PCI passthrough enables workloads that need raw hardware access: GPU compute, NVMe virtualisation, hardware crypto, USB device access. Done correctly, it is fast and reliable. Done incorrectly, it produces VMs that crash at boot.

Prerequisites

  • CPU with VT-d (Intel) or AMD-Vi.
  • IOMMU enabled in firmware.
  • Kernel parameter intel_iommu=on iommu=pt (or AMD equivalent).
  • VFIO modules loaded.
dmesg | grep -e DMAR -e IOMMU | head
find /sys/kernel/iommu_groups/ -type l | sort -V

Configure VFIO

Configuration change
cat > /etc/modprobe.d/vfio.conf <<EOF
options vfio-pci ids=10de:1b06,10de:10ec
softdep nvidia pre: vfio-pci
EOF
update-initramfs -u

The ids= line is the PCI vendor:device IDs of the devices to bind to VFIO at boot. Get them with lspci -nn.

Passing through a GPU

lspci | grep -i nvidia
qm set 100 --hostpci0 01:00,pcie=1,x-vga=1

Common options:

OptionPurpose
pcie=1Emulate a PCIe device (vs legacy PCI)
x-vga=1Mark as primary VGA (required for the boot display)
rombar=1Enable ROM BAR for legacy option ROM

For a complete GPU passthrough (display + audio):

qm set 100 --hostpci0 01:00,pcie=1,x-vga=1 --hostpci1 01:00.1

Passing through an NVMe controller

qm set 100 --hostpci0 05:00,pcie=1

USB passthrough

USB devices can be passed through by port:

qm set 100 --usb0 host=1234:5678

Or by port:

qm set 100 --usb0 host=1-2

TPM and Secure Boot

For Windows 11 or hardened Linux:

qm set 100 --tpmstate0 local-zfs:1,version=v2.0
qm set 100 --bios ovmf
qm set 100 --efidisk0 local-zfs:1,efitype=4m,pre-enrolled-keys=1

The pre-enrolled-keys=1 flag includes the standard Microsoft/UEFI Secure Boot keys.

Troubleshooting

SymptomLikely causeFix
“No IOMMU found”Firmware IOMMU off or kernel param missingEnable in BIOS; add intel_iommu=on
VM refuses to start, device in useHost driver claimed the deviceBlacklist host driver; ensure VFIO ids include the device
Code 43 in Windows guestVendor reset bug or hidden deviceCheck vendor-specific workarounds
GPU passthrough slowWrong PCIe generation or BAR issuesVerify PCIe link speed; enable rombar=1

A break/fix exercise

Break/Fixadvanced30 minvm

GPU passthrough VM fails to start

Symptoms

  • qm start 100 returns 'No IOMMU found, can't bind device'
  • Firmware settings show VT-d enabled
  • lspci shows the GPU

Available evidence

  • cat /proc/cmdline shows intel_iommu=on is NOT present
  • dmesg | grep -e DMAR -e IOMMU is empty
  • The host was upgraded recently
Show diagnosis & remediation

Root cause

The kernel command line lost the intel_iommu=on parameter after a GRUB/systemd-boot update. The firmware has IOMMU enabled, but the kernel does not know to use it.

Safe remediation

Edit /etc/default/grub (GRUB) or /etc/kernel/cmdline (systemd-boot) to add intel_iommu=on iommu=pt. For GRUB, run update-grub. For systemd-boot, run proxmox-boot-tool refresh. Reboot.

Verification

dmesg | grep -e DMAR -e IOMMU shows IOMMU active. qm start 100 succeeds. The VM sees the GPU.

Prevention

Document kernel command line requirements. Treat kernel or bootloader updates as a chance to verify the cmdline. Validate IOMMU activation after every kernel update.

Production considerations

Common mistakes

  • Forgetting to blacklist the host driver.
  • Confusing IOMMU group with PCI device.
  • Assuming a GPU works without x-vga=1.
  • Trying to live-migrate a passthrough VM without mediated passthrough support.

Key takeaways

  • Enable IOMMU in firmware and kernel command line.
  • Bind devices to VFIO; blacklist host drivers.
  • Passthrough requires the entire IOMMU group, not just one device.

Knowledge check

Knowledge check · 3 questions

  1. Q1. Which kernel parameter enables Intel IOMMU?

  2. Q2. Standard PCI passthrough pins a VM to its host and rules out live migration.

  3. Q3. Which file is used to bind PCI devices to VFIO at boot?

Passing score: 75%. Answers are checked in this browser.