NVIDIA vGPU on Proxmox VE: Mediated Devices Setup Guide

Passing an entire GPU through to a single virtual machine is straightforward on Proxmox VE: the card disappears from the host and becomes exclusively available to one guest. But what if you want several VMs to share one physical GPU — say, three engineering workstations pulling CUDA acceleration from a single RTX A5000, or a handful of VDI desktops splitting a data-center GPU's encode/decode engines? That's what NVIDIA vGPU and Linux mediated devices (mdev) are for, and Proxmox VE has first-class support for both.

This guide walks through the entire process on Proxmox VE 8.4 and 9.x: host prerequisites, driver installation, resource mapping, VM configuration, guest driver setup, and the handful of gotchas that trip people up the first time. It assumes you already have PCI(e) passthrough working conceptually (IOMMU enabled, VFIO understood) — if you've never done passthrough on this host before, get a plain GPU passthrough working first so you know your BIOS and kernel command line are correct before adding vGPU on top.

What Mediated Devices Actually Are

A mediated device is a software construct exposed by a physical device's driver that behaves like an independent PCI device to a VM, without the underlying hardware actually being split into separate PCI functions the way SR-IOV splits a NIC. The host driver "mediates" access to the shared physical GPU, presenting each VM with what looks like its own private graphics card.

Two ecosystems use this in Proxmox VE:

Intel GVT-g — built into older Intel integrated GPU drivers (5th–7th generation Core, and certain Xeon E3 v4–v6 parts). It's mostly deprecated on newer Intel hardware but still shows up in homelab setups with older hardware.
NVIDIA vGPU (GRID) — NVIDIA's commercial virtualization stack, which is the focus of this article. It requires a licensed vGPU-capable GPU (data-center cards like the T4, A2, A16, L4, L40, or the RTX PRO 6000 Blackwell Server Edition, and certain RTX Ax000 workstation cards) plus an NVIDIA vGPU software entitlement.

The key difference from ordinary PCI(e) passthrough is that the physical GPU never leaves the host. The host driver creates one or more mediated instances, each with a slice of the GPU's framebuffer, encode/decode engines, and compute capacity, and each instance is handed to a different VM via the hostpciX configuration option with an mdev= property.

Licensing and Hardware Reality Check

Before touching a config file, confirm two things, because neither can be worked around after the fact:

You need a genuine NVIDIA vGPU software entitlement. NVIDIA vGPU is licensed software distributed through NVIDIA's Enterprise/Virtual GPU program. Consumer GeForce cards are not supported by this official path (there are community "unlock" projects that patch the driver to work on unsupported consumer GPUs, but those are unsupported hacks outside NVIDIA's and Proxmox's support scope and are not covered here).
Your GPU must actually be listed in NVIDIA's vGPU support matrix for the driver branch you intend to run. As of this writing, NVIDIA vGPU Software 18.x is the branch validated against modern Proxmox VE 8.4/9.x kernels (6.8, 6.11, 6.14).

You'll also want a current Proxmox VE subscription (Basic, Standard, or Premium) if you plan to pull packages from the enterprise repository, though the no-subscription repository works fine for lab and non-production use.

BIOS/UEFI Prerequisites

Reboot into firmware setup and confirm the following are enabled. These matter more for vGPU than for ordinary passthrough because the virtual functions vGPU relies on (see SR-IOV below) depend on them:

Setting	Why it matters
Intel VT-d / AMD-Vi (IOMMU)	Required for any PCI passthrough, mediated or not
SR-IOV support	Ampere-generation and newer NVIDIA GPUs expose vGPU instances as SR-IOV virtual functions
Above 4G Decoding	Needed so the host can map the BARs of GPUs with large framebuffers
Alternative Routing-ID Interpretation (ARI)	Required for the higher-numbered virtual functions SR-IOV GPUs create

Some workstation cards, such as the RTX A5000, ship in a display-output mode by default and need NVIDIA's Display Mode Selector Tool run once to switch them into vGPU mode (which disables the physical display outputs — expected behavior, not a fault).

Step 1: Prepare the Host for Passthrough

If you haven't already enabled IOMMU on this host, do that first. On the kernel command line (edit /etc/kernel/cmdline on systems using proxmox-boot-tool, or the GRUB config otherwise):

# Intel
intel_iommu=on iommu=pt

# AMD
amd_iommu=on iommu=pt

Apply it and reboot:

proxmox-boot-tool refresh
reboot

Confirm IOMMU is active:

dmesg | grep -e DMAR -e IOMMU

Step 2: Run the vGPU Helper

Proxmox VE ships a helper script that handles the tedious groundwork — blacklisting the nouveau driver, installing kernel headers, and pulling in DKMS:

pve-nvidia-vgpu-helper setup

Reboot afterward so the nouveau blacklist takes effect and the GPU is left unclaimed by any host driver, ready for the vGPU driver to bind to it.

Step 3: Install the NVIDIA vGPU Host Driver

Download the host driver from NVIDIA's Virtual GPU Software portal (this requires your enterprise/entitlement login — the vGPU driver package is not publicly downloadable like consumer GeForce drivers). When selecting a hypervisor platform, choose Linux KVM — Proxmox VE uses KVM/QEMU under the hood, and the KVM driver package is what's compatible.

chmod +x NVIDIA-Linux-x86_64--vgpu-kvm.run
./NVIDIA-Linux-x86_64--vgpu-kvm.run --dkms

Answer yes when the installer asks to register the kernel module sources with DKMS — this is what keeps the driver working automatically across future kernel updates, which matters a lot on a rolling-release host like Proxmox VE. Reboot once installation finishes.

Verify the driver bound to the GPU:

nvidia-smi
lspci -d 10de: -nnk

The lspci output should show Kernel driver in use: nvidia against your GPU's PCI address.

Secure Boot Systems

If UEFI Secure Boot is enabled, unsigned out-of-tree kernel modules won't load by default. Install the shim tooling first:

apt install shim-signed grub-efi-amd64-signed mokutil

Run the driver installer with --dkms --skip-module-load and decline module signing when prompted, then build and install through DKMS explicitly:

dkms build -m nvidia -v  --force
dkms install -m nvidia -v  --force

Enroll the DKMS-generated key into UEFI via mokutil, reboot, and complete the MOK enrollment prompt at boot. Re-check with lspci -d 10de: -nnk to confirm the nvidia module is now in use.

Step 4: Enable SR-IOV Virtual Functions (Ampere and Newer)

Ampere-generation and later data-center/workstation GPUs expose their vGPU capability through SR-IOV virtual functions, which need to be switched on after the driver is loaded:

systemctl enable --now pve-nvidia-sriov@ALL.service

Confirm the virtual functions appeared alongside the physical GPU:

lspci -d 10de:

For example, an RTX A5000 will show its physical function plus 24 virtual functions spanning a contiguous PCI address range. Each virtual function is a candidate target for a mediated device later on.

Optional: Multi-Instance GPU (MIG)

On MIG-capable cards (currently the RTX PRO 6000 Blackwell Server Edition in the vGPU context), you can additionally hard-partition the GPU into isolated compute/memory slices before layering vGPU profiles on top:

nvidia-smi -i  -mig 1
nvidia-smi mig -lgip
nvidia-smi mig -cgi 47,47,47,47 -C

When using MIG together with vGPU, pick profiles with the +gfx suffix, since those are the ones built for vGPU compatibility. Tear a MIG configuration down with:

nvidia-smi mig -dci
nvidia-smi mig -dgi

Most homelab and single-GPU deployments can skip MIG entirely — it's aimed at data centers slicing one physical GPU across many tenants with hard isolation guarantees.

Step 5: Create a PCI Resource Mapping

Rather than hardcoding a specific virtual function's PCI address into every VM (which breaks if the host's PCI enumeration order ever changes), map the whole set of virtual functions once at the datacenter level:

In the web UI, go to Datacenter → Resource Mappings → PCI Devices → Add.
Give the mapping a name (e.g. gpu0).
Select all of the virtual functions belonging to your GPU.
Enable Use with Mediated Devices.

With this mapping in place, Proxmox VE will automatically pick an available virtual function for each VM at start time instead of you having to track which VF is free.

Step 6: Build the VM

Create the VM normally first — through the wizard or qm create — without any GPU attached yet. Standard guidance applies: use OVMF (UEFI) BIOS with a matching machine type for Windows guests expecting UEFI-based GRID drivers, and give the VM enough vCPU/RAM headroom for the workload you're targeting.

One detail that catches people out: the built-in VNC/SPICE console will not display the vGPU's output. The virtual display the vGPU driver creates isn't wired into Proxmox's console framebuffer. Plan on remote desktop access instead:

Windows 10/11 guests: enable Remote Desktop under Settings → System → Remote Desktop.
Linux guests (Ubuntu/Rocky): install a display manager such as LightDM, then run x11vnc against display :0 as a systemd service so you have a console to install the guest driver through.

Step 7: Attach the vGPU

Shut the VM down (mediated devices are assigned at boot, not hot-plugged), then find which mediated device types your mapping actually supports:

pvesh get /nodes//hardware/pci//mdev

This queries sysfs for the profiles the driver currently offers — note that on kernel 6.8 and newer, NVIDIA vGPU uses a custom low-level interface, so the list won't look identical to the classic mdevctl types output for other mdev drivers like Intel GVT-g, but Proxmox VE still manages them the same way from the operator's side.

Attach a vGPU profile via the CLI:

qm set VMID -hostpci0 01:00.4,mdev=nvidia-660

Or via the GUI: VM → Hardware → Add → PCI Device, select your mapping, and pick the desired mediated device type from the dropdown. The number in a profile name (e.g. nvidia-660) typically corresponds to the framebuffer allocation in MB for that profile — smaller numbers mean more instances fit on the same physical GPU, larger numbers mean fewer, more capable instances.

Start the VM and confirm the guest sees a GPU in Device Manager (Windows) or lspci (Linux) before installing anything further.

Step 8: Install the Guest (GRID) Driver

The guest driver is a different package from the host driver — it's the GRID driver matched to your vGPU software branch, downloaded from the same NVIDIA vGPU portal.

Windows

Download the matching package (for example 553.24_grid_win10_win11_server2022_dch_64bit_international.exe), run it, and reboot. After reboot, nvidia-smi inside the guest should report the assigned vGPU profile.

Ubuntu

apt install ./nvidia-linux-grid-550_550.127.05_amd64.deb
nvidia-xconfig

Rocky Linux

dnf install nvidia-linux-grid-550-550.127.05-1.x86_64.rpm
nvidia-xconfig

If you plan to run CUDA workloads inside the guest, check NVIDIA's compatibility matrix for which CUDA Toolkit version pairs with your specific vGPU driver branch before installing it — mismatches here are a common source of "driver/library version mismatch" errors that have nothing to do with Proxmox at all.

Licensing the Guest

A vGPU-enabled guest won't run at full, licensed capability until it can reach an NVIDIA licensing service — either NVIDIA's cloud licensing service or a self-hosted Delegated License Service (DLS), depending on your entitlement type. Two things matter here:

Configure the license client inside the guest per NVIDIA's licensing documentation for your driver branch.
Keep the guest's clock synchronized via NTP. Licensing handshakes are time-sensitive, and a guest with clock drift will silently fail to acquire or renew its license, which shows up as degraded performance or the driver falling back to an unlicensed/frame-rate-capped mode.

Troubleshooting

No mediated device types show up

This is almost always one of: the vGPU host driver isn't actually bound (check lspci -d 10de: -nnk for Kernel driver in use: nvidia), SR-IOV virtual functions weren't enabled on Ampere+ cards (re-run systemctl status pve-nvidia-sriov@ALL.service), or the resource mapping wasn't marked "Use with Mediated Devices."

PCIe AER (Advanced Error Reporting) warnings in dmesg

Consumer and prosumer boards frequently log AER correctable-error warnings against passthrough devices, vGPU-enabled GPUs included. These are typically harmless, though on some hardware combinations the errors are logged as "soft-recoverable" without actually being recovered cleanly — if you see these paired with actual guest instability, treat it as a hardware/firmware compatibility signal rather than something to patch around in Proxmox VE itself.

vGPU disappears after a Windows guest reboot

Windows Fast Startup interferes with vGPU re-initialization across a soft reboot. Disable it via Control Panel → Power Options → "Choose what the power buttons do" → uncheck Fast Startup, or from an elevated prompt:

Powercfg -h off

VM won't start after attaching the vGPU

Check journalctl -u pvedaemon and the VM's task log for the specific hostpci error. The most common causes are: the mdev profile requested is no longer available (another VM already consumed the last instance of that profile type), the VM's BIOS type doesn't match what the guest driver expects (OVMF vs SeaBIOS), or the host driver was updated and the module needs a rebuild — run dkms status to confirm the nvidia module built cleanly against the current kernel.

vGPU vs. Full PCI Passthrough vs. SR-IOV NICs — Which One Do You Actually Want?

It's worth being explicit about where vGPU fits, since the terminology overlaps with other passthrough techniques:

Full PCI(e) passthrough hands an entire physical device to one VM exclusively. Best when a single VM needs maximum, uncontended performance from the card and you don't need to share it.
NVIDIA vGPU (mediated devices), covered here, splits one physical GPU into multiple isolated virtual GPUs, each assigned to a different VM. Best when several VMs each need graphics/CUDA acceleration but none needs the whole card.
SR-IOV on network cards is a related-sounding but functionally different technology — it splits a NIC into real, independent virtual functions at the hardware level, rather than mediating shared access through a host driver.

If your goal is one gaming or workstation VM getting an entire GPU, ordinary PCI(e) passthrough is simpler and doesn't require any NVIDIA licensing. Reach for vGPU specifically when the workload is "several VMs, one GPU."

Frequently Asked Questions

Can I use vGPU with a regular GeForce card?

Not through NVIDIA's officially supported vGPU software — that requires a licensed data-center or workstation GPU on NVIDIA's vGPU support matrix. Community projects exist that patch the driver to run on unsupported consumer cards, but they sit outside NVIDIA's and Proxmox's support boundary, carry no update guarantees, and can break on any driver or kernel bump.

Do I need a Proxmox VE subscription to use vGPU?

No — vGPU itself works with the no-subscription repository. A subscription (Basic, Standard, or Premium) gives you access to the enterprise repository and official support, which is recommended for production but not required for a lab setup.

Can a mediated device be hot-plugged into a running VM?

No. Mediated devices are created and attached at VM boot and torn down at shutdown — attach the profile while the VM is off, then start it.

Can I live-migrate a VM with a vGPU attached?

Migrating a running VM with an attached mediated device is not something you should plan around the way you would a purely virtual VM — the mediated device is tied to host-side driver state on the source node. Treat vGPU-backed VMs as pinned to their host, and use offline migration (shut down, migrate, reattach the vGPU on the destination) if you need to move one.

How many VMs can share one GPU?

It depends entirely on the vGPU profile you choose. Profiles are named after their framebuffer allocation (e.g. a "660" profile allocates roughly 660MB per instance); smaller framebuffer profiles allow more concurrent instances on the same physical card, while larger ones allow fewer, more capable instances. Check pvesh get /nodes//hardware/pci//mdev to see exactly what your card and driver combination currently offers, including remaining available instances per profile.

Why can't I see anything in the Proxmox console for a vGPU VM?

The built-in VNC/SPICE console doesn't render the vGPU's virtual display output. Set up Remote Desktop (Windows) or VNC/x11vnc against the guest's own display server (Linux) before you rely on the vGPU for anything graphical — this is expected behavior, not a misconfiguration.

Closing Notes

NVIDIA vGPU on Proxmox VE is more involved than a standard PCI passthrough setup — there's a licensing step, a second driver package, and a resource-mapping layer that doesn't exist for ordinary passthrough — but the payoff is real GPU sharing across VMs instead of dedicating a whole card to a single guest. Get the host driver bound and SR-IOV functions visible first, confirm your mediated device types with pvesh, and only then start attaching profiles to VMs. Most of the friction people hit comes from skipping one of those verification steps and troubleshooting blind further down the chain.

Vormox is an independent virtualization management platform built on Proxmox VE. Proxmox® and Proxmox VE® are trademarks of Proxmox Server Solutions GmbH. Vormox is not affiliated with, endorsed by, or sponsored by Proxmox.

Setting Up NVIDIA vGPU (Mediated Devices) in Proxmox VE