Proxmox GPU Passthrough Script

Proxmox GPU Passthrough Script

GPU passthrough on Proxmox is one of the most requested and most painful configurations in the homelab world. The process involves editing grub, modifying kernel modules, identifying IOMMU groups, binding the right devices, and writing hook scripts — all from scattered forum posts and wiki pages. This script bundle detects your hardware, generates the correct configuration, and validates the result.

What's Included

• IOMMU detection script — Identifies all IOMMU groups, flags problematic groupings (ACS issue detection), and lists all passthrough-eligible devices
• Automated setup script — Configures GRUB/systemd-boot for IOMMU, adds vfio modules, and creates the correct modprobe blacklist for your GPU vendor (NVIDIA or AMD)
• VM hook script — Handles GPU bind/unbind around VM start/stop so the host reclaims the GPU when the VM is off
• Validation script — Post-reboot checker that confirms IOMMU is active, vfio is bound, and the device is ready to assign
• Multi-GPU guide — Notes and config snippets for setups with both an integrated GPU (for the host) and a discrete GPU (for the VM)

How It Works

• Run the detection script first — it prints a report of your IOMMU groups and identifies your target GPU
• Pass the GPU's PCI address to the setup script — it handles everything else
• Reboot, then run the validation script to confirm the setup is clean
• Copy the hook script into /var/lib/vz/snippets/ and reference it in your VM config
• Add the GPU to your VM in the Proxmox UI — it just works

What You Get

• detect-iommu.sh — IOMMU group report with passthrough eligibility flags
• setup-gpu-passthrough.sh — main setup script (GRUB + vfio + blacklist)
• gpu-hookscript.pl — Proxmox VM hook for bind/unbind on VM start/stop
• validate-passthrough.sh — post-reboot validation with clear pass/fail output
• README.md — full walkthrough, troubleshooting guide, and NVIDIA vs. AMD differences

Requirements

Proxmox VE 7.x or 8.x on bare metal (not a VM). CPU and motherboard with IOMMU support (Intel VT-d or AMD-Vi enabled in BIOS). A discrete GPU to pass through.