Black Friday mini PC deals are live, checked daily through Cyber Monday. See the deals guide
← All Guides
advanced

Proxmox GPU Passthrough: Pass a Whole GPU Into a VM

Proxmox GPU passthrough step by step: check IOMMU groups, load vfio, blacklist the host driver, build a q35 and OVMF VM, and fix Code 43 and shared groups.

Budget Homelab ·
proxmoxhow-tohardware

GPU passthrough is the hardest thing most people attempt in Proxmox, and the reason is not the configuration. The commands are short and there are not many of them. The difficulty is that success depends on how your motherboard happens to wire its PCIe slots, and you cannot find that out until you are several steps in.

This guide walks the whole path in order, with a verification step after each change so you find the wall early instead of after the reboot that drops your display. If you have not passed through any hardware before, USB passthrough is the gentler version of the same idea and worth doing first. If you have not decided whether this workload belongs in a VM at all, read VM vs LXC before you start, because for a lot of GPU jobs the honest answer is that you do not need passthrough.

Quick Answer: How to Pass a GPU to a Proxmox VM

  1. Enable VT-d (Intel) or AMD-Vi (AMD) plus Above 4G Decoding in the motherboard firmware
  2. Verify IOMMU with dmesg | grep -e DMAR -e IOMMU -e AMD-Vi (no kernel parameter needed on current Proxmox)
  3. Check IOMMU groups with pvesh get /nodes/$(hostname)/hardware/pci --pci-class-blacklist ""
  4. Load vfio, vfio_iommu_type1 and vfio_pci via /etc/modules-load.d/vfio.conf
  5. Blacklist the host GPU driver in /etc/modprobe.d/blacklist.conf
  6. Create the VM with q35 machine type and OVMF BIOS
  7. Attach with qm set <VMID> -hostpci0 <bus:slot>,pcie=on

The step that decides whether this works at all is step 3. Everything else is typing.

When Passthrough Is The Wrong Tool

Worth settling before you spend an evening on it, because passthrough is all-or-nothing: the VM gets exclusive ownership of the card and the host loses it completely.

Use an LXC container instead if you want hardware transcoding in Jellyfin, or a local LLM through Ollama, or anything else where one Linux workload wants acceleration. A container shares the host’s GPU, several containers can share the same card, and none of the configuration below applies. Hardware transcoding with QuickSync covers that path for media, and running a local LLM covers it for AI work. Note that Ollama runs perfectly well on CPU only, just slowly, so a GPU is an optimization there rather than a requirement.

Use full passthrough if the guest needs a driver stack the host cannot give it. A Windows VM for gaming or CUDA development, a guest where you want the vendor driver isolated from the hypervisor, or a card you want dedicated to one workload with no sharing. Those are real reasons. “It seems more proper” is not one.

If you are still choosing hardware, GPUs for self-hosted AI covers what is worth buying for that workload. Check current price on anything you shortlist, since GPU pricing moves fast.

Step 1: Firmware Settings

Reboot into BIOS or UEFI setup. Names vary by vendor, so hunt rather than expecting an exact match:

That last setting matters more than it looks. If the GPU you want to pass through is also the card drawing the host’s console, the host grabs it during boot and will not let go cleanly. On a system with integrated graphics, point the firmware at the iGPU and the problem disappears. On a system with two discrete cards, put the host on the weaker one. On a system with exactly one GPU and no iGPU, passthrough is possible but considerably more work, and you will be administering the node over SSH or the web UI from another machine either way.

Step 2: Confirm IOMMU Is Already On

This is where a lot of older walkthroughs will waste your time. SSH into the node and check:

dmesg | grep -e DMAR -e IOMMU -e AMD-Vi

You want a line reporting that IOMMU is enabled, such as DMAR: IOMMU enabled on Intel or an AMD-Vi initialization line on AMD.

Proxmox documents that AMD platforms enable IOMMU by default, and that kernels 6.8 and newer do the same on Intel. Proxmox VE 9 ships kernels past that point, so on a current install this usually just works and the intel_iommu=on parameter that every older guide opens with is no longer required. Check the kernel you are actually on:

uname -r

If IOMMU is already enabled, skip straight to step 4. Editing a bootloader config you did not need to touch is a way to create a problem you did not have.

Step 3: Kernel Command Line, Only If Needed

If step 2 found nothing, add the parameter. First find out which bootloader the node uses, because the file differs:

proxmox-boot-tool status

For systemd-boot (typical on a ZFS root install), edit /etc/kernel/cmdline. It is a single line:

root=ZFS=rpool/ROOT/pve-1 boot=zfs intel_iommu=on

Apply it:

proxmox-boot-tool refresh

For GRUB, edit GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub:

GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on"

Apply it:

update-grub

Then reboot and re-run the dmesg check from step 2. Do not move on until it reports IOMMU enabled, because every later step assumes it.

Two optional parameters you will see recommended. iommu=pt enables passthrough mode and can reduce overhead for devices the host still uses; it is safe and generally worth having. pcie_acs_override=downstream is a different animal and belongs in troubleshooting, not here. See step 4.

Step 4: Read Your IOMMU Groups

This is the step that decides the outcome. List the PCI devices with their groups:

pvesh get /nodes/$(hostname)/hardware/pci --pci-class-blacklist ""

You will get a table of devices with an iommugroup column. Find your GPU. It will normally appear as two entries sharing one group, the VGA controller and its audio function, at addresses like 01:00.0 and 01:00.1.

The rule: everything in an IOMMU group goes to the same guest, or none of it does. The group is the smallest unit the platform can isolate, and that boundary is set by how the board wires its PCIe lanes, not by anything you can configure.

Two outcomes:

Clean group. The GPU and its audio function are alone in their group. Carry on, this will work.

Shared group. The GPU shares a group with a SATA controller, a NIC, a USB controller, or an entire bundle of chipset devices. You cannot pass only part of it. Options, in the order worth trying:

  1. Move the card to a different physical slot. Best fix and often the whole answer. Slots wired directly to the CPU usually land in their own groups, while slots behind the chipset get bundled together. The motherboard manual’s block diagram tells you which is which.
  2. Pass the whole group. Fine if the other devices are things you do not need on the host. Not fine if the group contains the controller holding your boot drive.
  3. ACS override. Adding pcie_acs_override=downstream to the kernel command line makes the kernel split groups the hardware does not guarantee are isolated. It frequently works and it is genuinely a compromise: the isolation you are relying on is now assumed rather than enforced, so a guest could in principle reach memory belonging to another device in the real group. Acceptable for a hobby lab running workloads you trust. Not acceptable for a guest exposed to untrusted input or sitting next to data you cannot lose. Decide deliberately rather than pasting it in because a forum thread said to.

Enterprise boards tend to have good IOMMU separation because the platform was designed for virtualization. Consumer boards vary enormously between models from the same vendor. This is the single most important thing to check before buying hardware specifically for passthrough.

Step 5: Load The vfio Modules

vfio-pci is the stub driver that claims the device on the host so the guest can own it. Create /etc/modules-load.d/vfio.conf:

cat > /etc/modules-load.d/vfio.conf <<'EOF'
vfio
vfio_iommu_type1
vfio_pci
EOF

Refresh the initramfs and reboot:

update-initramfs -u -k all
reboot

Verify:

lsmod | grep vfio

Those three modules are the current list. Older guides include a fourth, vfio_virqfd, which was folded into the vfio core in kernel 6.2 and no longer exists as a separate module. Listing it does no real harm beyond a “module not found” complaint, but it is a reliable signal that the guide you are reading was written for a much older kernel than the one Proxmox is running, so treat the rest of its advice with the same suspicion.

Step 6: Blacklist The Host Driver

The host and the guest cannot both drive the card. If the host’s driver binds first, passthrough fails. Add the relevant entries to /etc/modprobe.d/blacklist.conf.

For an NVIDIA card:

echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
echo "blacklist nvidia" >> /etc/modprobe.d/blacklist.conf

For an AMD card:

echo "blacklist amdgpu" >> /etc/modprobe.d/blacklist.conf
echo "blacklist radeon" >> /etc/modprobe.d/blacklist.conf

Then rebuild and reboot:

update-initramfs -u -k all
reboot

Before you reboot, make sure you can reach this node another way. Blacklisting the graphics driver on a host whose console runs on that card means the console goes dark. That is expected and the node is still running, but you want SSH access or the web UI from another machine confirmed working first, not discovered afterwards.

Confirm the host’s vendor driver no longer claims the device:

lspci -nnk -d ::0300

The Kernel driver in use: line should read vfio-pci, or be absent entirely, because Proxmox binds the device when the VM starts. If it names nouveau, nvidia, amdgpu or radeon, the blacklist did not take.

Step 7: Build The VM Correctly

Two settings are not optional for GPU passthrough, and both are much easier to set at creation time than to change later.

SettingValueWhy
Machine typeq35Provides a real PCIe topology; the default i440fx is PCI only
BIOSOVMF (UEFI)Modern GPUs expect a UEFI environment
EFI diskAddedRequired by OVMF to store firmware variables
CPU typehostPasses CPU features through rather than emulating a generic model

Create the VM, then install the guest operating system and confirm it boots normally on the virtual display before adding the GPU. Adding passthrough to a VM that was already broken for an unrelated reason turns one problem into two, and you will spend the evening debugging the wrong one.

Step 8: Attach The GPU

Stop the VM, then attach the device using the address from step 4:

qm set 100 -hostpci0 01:00,pcie=on

Passing 01:00 without a function number attaches all functions in that slot, which is what you want for a GPU and its audio function together.

The web UI equivalent is Hardware > Add > PCI Device, with “All Functions” ticked and “PCI-Express” checked.

One option worth understanding rather than copying:

Start the VM and check from inside the guest. On Linux:

lspci -nnk

On Windows, open Device Manager and look under Display adapters. Then install the vendor driver and confirm the card reports no error state. Until a driver is loaded and the device reports healthy, the GPU is visible but not usable, and “it shows up in lspci” is not the same claim as “it works.”

When It Does Not Work

“Failed to assign device” on VM start. Usually the host still has the device, or interrupt remapping is unavailable. Re-check that lspci -nnk shows no vendor driver (nouveau, nvidia, amdgpu, radeon) in use, and that the blacklist survived the reboot.

Host console goes black and stays black. Expected after step 6 if the host was using that card. The node is up; reach it over SSH or the web UI. If you need the console back, remove the blacklist entries and rebuild the initramfs.

Guest boots but the GPU shows an error. Check the IOMMU group again. A card that appeared to attach while a grouped sibling stayed on the host produces exactly this.

Single-GPU system. The host claims the card during boot before anything you configured gets a say. Adding video=efifb:off to the kernel command line stops the host’s framebuffer from taking it. Some cards additionally need their VBIOS dumped to a file and referenced with the romfile option on the hostpci line. This is the genuinely hard case, and if a second GPU or an iGPU is available at all, using it is worth more than any amount of configuration.

NVIDIA Code 43 in Windows. The old symptom of the driver refusing to run in a VM. NVIDIA dropped that restriction from consumer drivers in 2021, so on a current driver it should not appear. If it does, verify q35 and OVMF are both actually set and the driver is current before reaching for the old hidden CPU-flag workarounds.

The Honest Summary

Passthrough is a configuration problem wrapped around a hardware constraint. The configuration is eight steps and most of them are one command. The constraint is your motherboard’s IOMMU groups, and no amount of config fixes a board that bundles your GPU with the controller running your boot drive.

So check the groups first. If they are clean, the rest of this is a couple of hours of careful work with a reboot between each step. If they are not, decide between a different slot, a different board, and an ACS override you have thought about rather than pasted in.

And before any of it, make sure you actually need a whole GPU handed to one guest. For most homelab GPU work, a container sharing the host’s card is less configuration, less fragility, and more flexibility. Passthrough earns its complexity when the guest needs its own driver stack, and not much before that.