Enable PCI and GPU passthrough

What it does

Checks that this Proxmox VE node is running on supported x86_64 hardware with an active IOMMU, then discovers every NVIDIA PCI function and configures it for VFIO passthrough after the next reboot. It adds the appropriate Intel VT-d or AMD IOMMU kernel parameter, loads VFIO from the initramfs, and reserves every discovered NVIDIA device ID for vfio-pci before its usual host driver can claim it.

Run it as root on the node that physically contains the device. It changes only that node's boot and module configuration; it does not modify a VM, migrate a device, or change cluster-wide configuration. It configures all NVIDIA PCI devices on the node, including GPU audio functions and any NVIDIA non-GPU hardware, so use it only when every NVIDIA device may be dedicated to guests. Shut down any guest that will use the device before rebooting the node. A passed-through GPU can no longer be used by the Proxmox host, so retain out-of-band or SSH access if it is the host's display adapter.

Before running the script, enable IOMMU in the server firmware: SVM/AMD-V and IOMMU on AMD systems, or Intel Virtualization Technology and VT-d on Intel systems. For GPUs, enable Above 4G Decoding when the firmware offers it. The script cannot change firmware settings; it verifies their effective result by requiring active Linux IOMMU groups.

After its first successful run, the script records version 1.0.0 in /var/lib/hero4hire/system-scripts/proxmox-9.2-x86_64-enable-pci-passthrough.version. Later runs stop before changing the node, including when a newer downloaded script has a different version. Remove that marker only after reviewing the existing boot and VFIO configuration; it is not a routine retry mechanism.

bash -c "$(curl -fsSL 'https://hero4hire.com/scripts/proxmox-9.2-x86_64/enable-pci-passthrough.sh')"

Loading script…

How it works

The CPU virtualization flag is only a preliminary check. The decisive firmware check is the presence of populated /sys/kernel/iommu_groups: without them, DMA isolation is not active and the script exits without changing files. lspci -Dnnd 10de: discovers every PCI function whose vendor ID is NVIDIA (10de), then the script confirms each one exists and belongs to an IOMMU group. Inspect a group before proceeding with find /sys/kernel/iommu_groups/N/devices -maxdepth 1 -printf '%f\\n'; devices in the same group must remain together on the host or be passed through together.

The script first sets a standard administrative PATH, since Proxmox boot tools such as update-initramfs, update-grub, and proxmox-boot-tool are commonly installed in /usr/sbin. It then selects amd_iommu=on for AMD or intel_iommu=on for Intel and adds iommu=pt. On hosts using Proxmox's proxmox-boot-tool, it updates /etc/kernel/cmdline and refreshes the boot entries. On GRUB hosts such as pve-01, it adds a small /etc/default/grub.d/ fragment and regenerates GRUB. Its dedicated VFIO files are backed up before replacement, and update-initramfs makes the modules and PCI-ID binding available early in boot. It deliberately does not blacklist broad GPU drivers: binding the selected vendor/device IDs to VFIO early avoids disabling unrelated GPUs of the same vendor.

This detects multi-function GPU hardware automatically. For example, on the inspected pve-01, it finds the RTX 3060 graphics function 01:00.0 and its audio controller 01:00.1; their IOMMU group contains exactly those two functions. It also means an NVIDIA NIC, USB controller, or other NVIDIA hardware would be configured if present. After reboot, use the Proxmox UI's Hardware → Add → PCI Device, or qm set, to assign the verified device(s) to a stopped VM. PCI devices are node-local and prevent normal VM migration unless equivalent hardware and a Proxmox resource mapping are configured on destination nodes.

The completion marker is written only after the boot configuration and initramfs update succeed. It stores the script version for auditability, but intentionally blocks matching and newer versions so a revised script cannot silently repeat node-level hardware changes. A failed run creates no marker and can be corrected and retried.

Commands Used

References

Proxmox VE documents general PCI(e) passthrough requirements and IOMMU activation, host PCI-device assignment and PCI resource mappings for clusters. The Linux kernel documents the VFIO interface and IOMMU group model.