Install NVIDIA Drivers on the Host

Hardware: GPUs and Coral-TPU~20 minView script

Install the NVIDIA proprietary driver on a Proxmox VE host using ProxMenux. The installer handles kernel compatibility, nouveau blacklisting, VFIO configuration, persistence service and can propagate the driver to any LXC container that already has NVIDIA passthrough configured.

What this does

ProxMenux automates the whole NVIDIA driver lifecycle on the host: detects your GPU, picks a driver version that is compatible with your running kernel, blacklists nouveau, downloads and runs the official NVIDIA .run installer with DKMS, installs the nvidia-persistenced service and udev rules, and offers to apply the optional NVENC patch. If you already have LXC containers with NVIDIA passthrough, it can update the userspace libraries inside them so their version matches the host.

Who is this for?

If you have an NVIDIA GPU and you want to use it for hardware-accelerated transcoding in Plex, Jellyfin, Frigate, Immich, Stable Diffusion or any other app running inside an LXC container, you need to install the driver on the Proxmox host first. This page covers that host-side install. Passing the GPU to a virtual machine (VM) uses a different flow (VFIO passthrough) and is documented separately.

Before you start

An NVIDIA GPU physically installed in the host. The script auto-detects it; AMD and Intel GPUs are not handled here.
lspci | grep -i nvidia
The GPU is not currently assigned to a VM via VFIO passthrough. If it is, the script will refuse to install the host driver to avoid breaking the passthrough config.
Internet access on the host. The installer downloads the driver from download.nvidia.com and, optionally, clones nvidia-persistenced and nvidia-patch from GitHub.
About 2 GB of free space in /opt/nvidia (workdir) plus the RAM used during the install. A reboot is required at the end.

GPU assigned to a VM? Stop here

If the GPU is currently bound to vfio-pci (i.e. it is being passed through to a VM), installing the host driver can break the passthrough and destabilise the system. ProxMenux detects this and aborts. Remove the GPU from the VM passthrough configuration and reboot before running this script.

Running the installer

Open ProxMenux on the host, go to Hardware Graphics → NVIDIA GPU Driver Installer. What you see depends on whether a driver is already present.

Hardware Graphics menu with the NVIDIA GPU Driver Installer entry highlighted

How the script runs

The installer goes through three phases with clear separation between "collecting information and validating" and "actually touching the host". Until the final confirmation, nothing has been changed.

┌─────────────────────────────────────────────┐
│  PHASE 1 — Detect, validate, pick version   │
│  (nothing touched yet)                      │
└──────────────────┬──────────────────────────┘
                   ▼
      ┌────────────┴────────────┐
      ▼                         ▼
  lspci detects             GPU bound to
  NVIDIA GPU(s)             vfio-pci? ──→ Abort
      │                         │        (remove VM
      │                         No        passthrough first)
      ▼
  nvidia-smi: driver already installed?
      │
      ├─ No  → continue (fresh install)
      └─ Yes → ask: Reinstall/Update  OR  Remove
                     │
                     ├─ Remove    → complete uninstall
                     │               + reboot prompt
                     └─ Reinstall → continue
      │
      ▼
  Show install overview
  (GPU list + current driver +
   LXC containers with NVIDIA passthrough)
      │
      ▼
  Kernel-compat filter:
  ├─ Kernel 6.17+   → driver 580.82.07+
  ├─ Kernel 6.8–16  → driver 550+
  ├─ Kernel 6.2–7   → driver 535+
  └─ Kernel 5.15+   → driver 470+
      │
      ▼
  User picks version (or "Latest")
                   │
     ┌─────── Cancel   OR   Confirm ────┐
     ▼                                  ▼
 Exit, nothing            ┌─────────────┴──────────────┐
 was changed              │  PHASE 2 — Install driver  │
                          └─────────────┬──────────────┘
                                        ▼
                          Prepare host:
                          ├─ Install pve-headers-$(uname -r)
                          ├─ Install build-essential + dkms
                          ├─ Blacklist nouveau + unload
                          │  └ /etc/modprobe.d/nouveau-blacklist.conf
                          ├─ Write modules-load config
                          │  └ /etc/modules-load.d/nvidia-vfio.conf
                          ├─ Stop/disable nvidia services
                          └─ Unload residual nvidia modules

                          If different version already present:
                          └─ clean uninstall first (apt purge,
                             remove DKMS entries)
                                        │
                                        ▼
                          Download NVIDIA .run installer
                          to /opt/nvidia (validate size +
                          executable signature)
                                        │
                                        ▼
                          Run installer with --dkms
                          --disable-nouveau --no-nouveau-check
                                        │
                                        ▼
                          Install udev rules
                          └─ /etc/udev/rules.d/70-nvidia.rules
                          + clone NVIDIA/nvidia-persistenced
                                        │
                                        ▼
                          update-initramfs -u -k all
                                        │
                                        ▼
                          nvidia-smi — verify driver loaded
                                        │
                        ┌───────────────┴───────────────┐
                        │  PHASE 3 — Optional extras    │
                        └───────────────┬───────────────┘
                                        ▼
                          LXC containers with NVIDIA?
                          ├─ Yes → offer driver propagation
                          │        (Alpine: apk · Arch: pacman ·
                          │         Debian/others: extract .run)
                          └─ No  → skip
                                        │
                                        ▼
                          keylase/nvidia-patch (NVENC limit)?
                          ├─ Yes → clone + apply
                          └─ No  → skip
                                        │
                                        ▼
                          Reboot prompt — required to finalize
                          nouveau blacklist + load new module

Step 1

GPU detection and overview

The script scans the PCI bus and shows every NVIDIA video controller it finds, the current driver status (or "No NVIDIA driver installed"), and any LXC container that already has NVIDIA passthrough configured (driver version inside each one).

Review the overview carefully. If the detected GPU is not what you expect, or if a container's version already matches the host, you can cancel here without side effects.

Pre-install overview showing detected GPUs, current driver status and LXC containers with NVIDIA passthrough

Step 2

Choose the driver version

ProxMenux fetches the list of available drivers from NVIDIA and filters out versions that are not compatible with your running kernel. The Latest available option is almost always the right pick.

The compatibility matrix the script uses:

Kernel	Typical PVE version	Minimum NVIDIA driver
6.17+	Proxmox VE 9.x	`580.82.07` or newer
6.8 – 6.16	Proxmox VE 8.2+	`550.x` or newer
6.2 – 6.7	Proxmox VE 8.0 – 8.1	`535.x` or newer
5.15+	Proxmox VE 7.x (legacy)	`470.x` or newer

Why kernel matters

Kernel 6.17 introduced internal API changes that break older NVIDIA drivers. If you install a driver below the minimum for your kernel, DKMS will fail to build the module and the GPU will not be available after reboot. ProxMenux filters the list so you can't pick an incompatible version by accident.

Driver version selector with kernel-compatible versions, Latest available on top

Step 3

Clean uninstall (only if reinstalling)

If a driver is already present and you picked a different version, ProxMenux stops the NVIDIA services, unloads the kernel modules, removes DKMS entries and purges nvidia-* / libnvidia-* / cuda-* packages before touching the new installer. This avoids the classic mixed-version mess.

Step 4

Prepare the system

Behind a single confirmation, the script:

Installs pve-headers-$(uname -r) (or proxmox-headers-$(uname -r)), build-essential and dkms.
Creates /etc/modprobe.d/nouveau-blacklist.conf blacklisting nouveau, and tries to unload it immediately.
Writes /etc/modules-load.d/nvidia-vfio.conf with vfio, vfio_pci, nvidia, nvidia_uvm and related modules.

Step 5

Download and run the NVIDIA installer

The installer downloads the NVIDIA-Linux-x86_64-<version>.run file into /opt/nvidia, validates it (size + executable signature, not just HTTP 200), then runs it with DKMS so the kernel module rebuilds automatically across kernel upgrades.

# What ProxMenux runs under the hood (you don't have to type this):
sh NVIDIA-Linux-x86_64-<version>.run \
  --no-questions \
  --ui=none \
  --disable-nouveau \
  --no-nouveau-check \
  --dkms

Download progress followed by the NVIDIA installer running its DKMS build

Step 6

Persistence service and udev rules

ProxMenux then installs nvidia-persistenced and writes udev rules at /etc/udev/rules.d/70-nvidia.rules so /dev/nvidia* device nodes appear reliably on boot. Without these, LXC passthrough can race on container startup and end up with a container that can't see the GPU.

Step 7

Optional: apply the NVENC patch

Consumer NVIDIA GPUs (GeForce line) limit the number of simultaneous NVENC encoding sessions. The community keylase/nvidia-patch removes that restriction. If you plan to use the GPU for Plex / Jellyfin / Frigate with many concurrent streams, answer Yes when prompted.

Check patch support for your driver

The patch does not cover every driver version. Before relying on it in production, verify your version is listed in the patch table. If it isn't supported yet, pick a nearby older driver that is.

Step 8

Optional: propagate the driver to LXC containers

If the overview screen listed containers with NVIDIA passthrough, ProxMenux now offers to update the userspace libraries inside each one to match the host. Host kernel module and container userspace must be the exact same version — otherwise nvidia-smi inside the container will fail with a "version mismatch" error.

The update is distro-aware: apk for Alpine, pacman for Arch, and the same .run installer (with --no-kernel-modules --no-dkms --no-install-compat32-libs) for Debian/Ubuntu and other distros. It temporarily raises container RAM to 2 GB if lower, runs the install, then restores the original RAM setting.

Prompt listing LXCs with NVIDIA passthrough and current driver version, with Yes/No to update them all

Step 9

Reboot

Finally, the script rebuilds initramfs for all kernels and offers to reboot. A reboot is required: the nouveau blacklist and the new kernel module only take effect after restart.

Reinstall or uninstall

When the installer detects that a NVIDIA driver is already loaded (nvidia-smi returns a version), it doesn't silently re-install on top. Instead it shows an action menu so you can choose what to do.

Reinstall / update

Continues with the normal install flow but, before downloading anything, runs a clean removal of the current driver (apt purge + DKMS entries dropped + leftover modules unloaded). This is the safe path to apply a newer driver version, switch branches when the kernel demands it, or recover from a half-broken state. The LXC propagation and NVENC patch prompts re-run at the end.

Uninstall — what gets removed

Confirms with a yes/no dialog first. Then performs a full, idempotent rollback:

Stops and disables nvidia-persistenced, unloads the kernel modules (nvidia_uvm, nvidia_drm, nvidia_modeset, nvidia) — any LXC container with NVIDIA passthrough will be cleanly cut off.
Runs apt purge on every NVIDIA package, removes the DKMS source tree and the /opt/nvidia .run installer cache.
Reverts the nouveau blacklist (/etc/modprobe.d/nouveau-blacklist.conf) and the modules-load config (/etc/modules-load.d/nvidia-vfio.conf) so nouveau can come back if you want generic graphics again.
Removes the udev rules (/etc/udev/rules.d/70-nvidia.rules) and the NVENC patch state file (if the keylase patch was applied earlier).
Rebuilds initramfs for all kernels and prompts for a reboot to finalise (the nouveau unblacklist only takes effect after restart).

LXC containers with NVIDIA passthrough

Removing the host driver invalidates the device paths and CUDA libraries mapped into any LXC with NVIDIA passthrough. Plan the operation during a maintenance window if Frigate / Plex / Jellyfin / Ollama (or anything else) depends on it.

Update notifications

The installed NVIDIA driver is tracked in ProxMenux's managed-installs registry. On startup and every 24h the Monitor checks the upstream listing at download.nvidia.com/XFree86/Linux-x86_64/ against the version nvidia-smi reports, and fires a notification when a newer compatible version is available.

Two kinds of update message

Same-branch patch. A newer maintenance release in your current driver branch (e.g. installed 580.65.06 → available 580.105.08). Bug fixes and security patches without changing branch.
Branch upgrade required by kernel. If the host is on a kernel that no longer supports your current branch (e.g. you upgraded the host kernel to 6.17 while still on driver 570.x), the message says so explicitly and recommends the kernel's minimum compatible branch — same matrix the installer uses to filter the version menu.

Anti-cascade by design

One notification per distinct upstream version, never on every 24h scan. The branch-upgrade message in particular only fires once you actually need to switch — until then the same-branch tracker stays muted.

Applying the update

The Monitor doesn't auto-apply driver updates — reinstalling the NVIDIA driver always needs a reboot. Open the same installer entry described above, pick Reinstall / update, and the new version is downloaded, the DKMS module rebuilt against the running kernel, and the reboot prompted at the end.

Verifying the install

Once the host is back up, log in over SSH or the Proxmox shell and run:

nvidia-smi

You should see your GPU listed, the driver version on the top border, and no processes yet (nothing is using the GPU at this point). Then check the persistence service:

systemctl status nvidia-persistenced

Output of nvidia-smi on the host showing the detected GPU and installed driver version

Troubleshooting

`nvidia-smi` says 'NVIDIA-SMI has failed'

Almost always a nouveau still loaded or a kernel header mismatch. After reboot, run lsmod | grep nouveau — if it returns anything, the blacklist didn't take effect (check /etc/modprobe.d/nouveau-blacklist.conf exists and rebuild initramfs with update-initramfs -u -k all, then reboot). If nouveau is gone, check dmesg | grep -i nvidia — DKMS build errors usually mean your kernel headers don't match the running kernel; reinstall them with apt install --reinstall pve-headers-$(uname -r).

LXC container can't see the GPU after host update

The container's userspace libraries are stuck at the previous driver version. Either re-run the NVIDIA installer and accept the LXC propagation prompt, or install the same driver version manually inside the container with --no-kernel-modules.

Check the install log

Every install writes to /tmp/nvidia_install.log. If something fails silently, that file has the full output (downloads, DKMS build, service installs). Attach it when reporting issues on GitHub.

Looking for the manual steps?

The original community guide — installing everything by hand with wget and ./NVIDIA-Linux-...run — is still available as a reference under Guides → NVIDIA. It's useful if you want to understand every command the ProxMenux installer runs, or if you're troubleshooting an unusual setup. For day-to-day installs, use ProxMenux — it's the path that keeps receiving fixes (kernel compatibility, LXC propagation, VFIO safety checks).

Add GPU to VM (Passthrough) — pass the NVIDIA GPU to a VM (different binding model from LXC).
Add GPU to LXC — share the NVIDIA GPU with one or more containers.
Switch GPU Mode (VM ↔ LXC) — toggle the same GPU between passthrough (VM) and shared (LXC) modes.
ProxMenux Monitor — Hardware tab — the GPU modal that triggers this installer in one click, plus live monitoring once it's done.
GPU Passthrough commands — lspci / dmesg / IOMMU / nvidia-smi reference.

ProxMenux Scripts: Previous

Uninstall Optimizations

ProxMenux Scripts: Next

Install Coral TPU (Host)