GPU passthrough on Proxmox: requirements, recovery and pitfalls

Give your VM a GPU without giving away your way back into the host. Start with IOMMU groups, keep a separate recovery route, then test the guest’s workload and restart behaviour. That gets you beyond the exciting first boot to a setup you can actually use.

Requirements from Proxmox, Linux and QEMU documentation; examples are illustrative.

Decide who owns the GPU

Write down why the guest needs the physical GPU and what the host currently needs from it. A display requirement, a compute workload and a desire to keep applications separate are different reasons. Define the operation the guest must complete and the host capabilities that must remain available.

The Proxmox PCI passthrough documentation states that a passed device is unavailable to the host and other VMs. That is the scope of whole-device assignment. Do not treat it as a method for sharing the same whole GPU simultaneously between those owners or as a way to create additional physical GPU memory.

Keep whole-device assignment separate from mediated or virtual GPU products and from application access to a host-owned device. If sharing is the actual requirement, investigate the exact supported sharing stack, drivers and entitlement rather than assuming ordinary passthrough provides it.

The Proxmox versus direct Docker guide covers the earlier architecture choice. If the workload can run under the host’s hardware ownership and that arrangement meets its isolation requirements, direct assignment may add a recovery dependency without solving the original problem.

Work out who keeps what

Work through these decisions before changing your working host.

Requirement or observation	Your next move	Evidence needed before proceeding
The host still needs the same whole GPU	Keep it host-owned or redesign the roles	A supported ownership plan that preserves required host functions
The GPU is the only verified host recovery display	Defer assignment	An independent recovery route demonstrated before changes
Hardware or firmware IOMMU support is uncertain	Defer	Exact platform documentation and the running system’s reported state
Group members include devices the host must retain	Review the topology and supported alternatives	Inventory of every member and a viable ownership/isolation arrangement
The guest boots but the expected GPU display is absent	Separate console expectations from device detection	Guest inventory, driver and the intended display or workload path
The first start works but a later start fails	Treat lifecycle acceptance as incomplete	Repeated start/stop observations, versions and relevant logs
Migration or replacement-host recovery is essential	Verify that requirement separately	Explicit support and a completed recovery or migration test

Plan what the host and guest will each retain after you assign the device.

Verify the complete hardware and software combination

Record the CPU and motherboard, board firmware, GPU and its firmware identity, installed slot, Proxmox release and kernel, VM machine type, guest firmware, operating system and driver. Keep this inventory in your own maintenance notes.

Proxmox requires suitable IOMMU and interrupt-remapping support across the platform. Use your platform documentation, then verify IOMMU and interrupt-remapping status on the running host.

Review the documentation for the installed release rather than collecting boot parameters from unrelated tutorials. Current defaults and old instructions can differ. Change only a requirement that has been identified for the actual combination, preserve the previous configuration and plan how to undo it.

For a second-hand GPU or platform, resolve identity and firmware access before adding assignment complexity. The used enterprise gear checklist distinguishes a documented maintenance route from an unidentified part that happens to boot.

Understand groups before detaching devices

The Linux VFIO documentation describes an IOMMU group as a set isolatable from the rest of the system and uses groups as ownership units. That is why the review extends beyond the GPU’s most visible function.

Inventory the full group and identify what every member does. Distinguish related GPU functions and bridges from an unrelated device whose loss would remove a host capability. Do not assume either that every GPU must appear completely alone or that every group member should be blindly assigned to the guest.

If the arrangement would detach storage or another device the host needs, stop and review supported alternatives. Try a supported alternative slot or platform configuration, then inspect the resulting groups again.

Keep hardware isolation and interrupt safeguards intact. A software change to group presentation can leave the underlying isolation problem unresolved.

Keep a recovery route before boot changes

Describe how the host would be accessed and repaired if the assigned GPU no longer provides the expected display or if the VM cannot start. Verify that route before changing boot settings, driver binding or the normal display role. Keep the recovery instructions available outside the guest.

Try your integrated GPU, spare display adapter or management facility as the recovery route. Verify which display the firmware selects after your changes.

Preserve the working host and VM configuration and identify a rollback procedure that remains available without the guest. The headless boot and recovery guide covers the separate difference between configured recovery features and recovery that has actually been demonstrated.

Host boot configuration also needs positive identification. Proxmox’s system administration documentation explains how to determine the bootloader; it calls the output of proxmox-boot-tool status an indication of the boot arrangement. Identify the active bootloader before applying its update procedure.

Match the guest firmware and driver deliberately

Proxmox recommends q35, OVMF and PCIe for GPU compatibility, while conditioning OVMF use on a UEFI-capable GPU ROM. Its documentation also distinguishes PCI assignment from PCIe presentation. Match those settings to your GPU and guest before changing an existing installation.

Choose the guest configuration as a supported combination. Check the intended GPU driver and workload against the guest operating system, and preserve a recoverable guest installation before changing its boot environment. Do not copy a ROM from another card merely because its marketing model sounds similar.

Keep host binding and guest driver installation as separate observations. Verify the guest driver, its output and the application workload in turn. Recording each stage makes failures easier to locate.

Avoid indiscriminate driver blacklists that may affect another GPU the host needs. If a documented binding change is required, scope it to the intended role and verify both host access and guest operation afterwards.

Separate the console from GPU detection

Proxmox documents that the assigned GPU’s framebuffer is not shown by its noVNC or SPICE console. A viewer attached to a virtual display and a workload using a passed physical GPU are therefore different things to check.

Decide what output the workload actually needs. Record the intended display route where graphical output matters, and test that route separately from device enumeration. Do not conclude that assignment failed solely because the expected physical GPU picture is absent from the web console.

Inside the guest, check the documented device and driver inventory, then perform the intended operation. A detected adapter, a driver status message and a completed workload provide different levels of evidence. Keep the observation precise instead of collapsing them into a single statement that passthrough works.

Test shutdown and restart as well as the first launch

Plan the lifecycle test before accepting the configuration. Start from a known host and guest state, check the intended workload, shut the guest down normally and start it again. Also examine the guest reboot and the host restart sequences that your setup requires.

Record failures with the transition that preceded them. A problem after guest shutdown is not the same observation as failure at host boot or driver installation. Preserve versions, configuration and relevant logs before changing settings or adding a purported reset workaround.

Diagnose a restart failure from its logs and exact hardware, firmware and software versions. After a repair, repeat the failing transition.

Compare performance under the same workload conditions if VM overhead matters to your decision.

Separate backup, replacement and migration requirements

List what the recovery plan contains and what it depends on. A replacement host also needs the required physical device, firmware behaviour and group arrangement. Record these dependencies alongside the VM backup and test recovery.

The current Proxmox documentation describes a conditional, experimental device-migration mapping option. That means neither “all passed GPUs migrate” nor “passthrough can never migrate” is an accurate blanket statement. Check the installed release, exact hardware and driver support rather than building a one-box plan around an untested feature.

QEMU’s VFIO migration documentation explains device-state saving and restoration and includes device-capability conditions. Verify those device capabilities on your platform and test migration separately from local VM startup.

For a single-host setup, make a practical recovery decision even if live migration is irrelevant. State whether downtime for repairing or replacing the host is acceptable and what needs to be available for the guest workload to return. Do not imply that a VM abstraction removes a physical hardware dependency.

Keep a repeatable setup checklist

Keep this checklist with your saved configuration.

Stage	Record	Acceptance question
Baseline	Hardware/software inventory, group members and saved configuration	Can the working state and required host access be recovered?
Assignment	Intended device functions and host/guest ownership observations	Was only the planned capability moved?
Guest operation	Driver state, display route where needed and actual workload result	Does the guest perform the required task?
Lifecycle	Guest shutdown/start, guest reboot and required host restart observations	Does the required sequence work repeatedly?
Recovery	Restored configuration/data and physical-device dependencies	Can the intended workload be recovered under the stated scenario?
Change review	Firmware, kernel, guest driver or slot changes since the accepted baseline	Which earlier observations need to be repeated?

If a required stage fails, keep the GPU host-owned while you fix the design. Once ownership, isolation, recovery and repeatable guest operation line up, you have a useful baseline to revisit after updates.

Want the guest to own physical USB ports too? Our PCIe USB card guide compares controller layouts and shows how to map the right PCI devices to your VM.