Install NVIDIA Drivers on 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.

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.

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.

Step 2

Choose the driver version

docs.hardware.nvidiaHost.walkthrough.version.body1

If the currently installed driver was patched via keylase (NVENC), the picker auto-narrows to versions still covered by the patch table, so applying <em>Reinstall / update</em> without losing the patch is one click.

How kernel compatibility is validated

The version list is filtered by NVIDIA branch maintenance and GPU PCI support, not by a hard-coded kernel/driver matrix. After selection, DKMS builds the module against the running kernel. A failed build stops the installation from being treated as valid; choose another maintained branch if NVIDIA has not adapted that release to your kernel.

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 the ProxMenux-owned /etc/modprobe.d/proxmenux-nouveau-blacklist.conf with blacklist nouveau and options nouveau modeset=0, records whether it added the companion line to blacklist.conf, and tries to unload the module immediately.
• Writes /etc/modules-load.d/nvidia-vfio.conf with nvidia and nvidia_uvm so the modules load early at boot.

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

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.

docs.hardware.nvidiaHost.walkthrough.propagate.body2

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 the nvidia kernel module is currently loaded and 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. (Binaries present on disk but the module not loaded do not count as installed — the module has to be live.)

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 same-branch version, choose another maintained branch when needed, 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:

• Runs nvidia-uninstall --silent first (the counterpart to the .run installer), then stops and disables nvidia-persistenced and nvidia-powerd, and 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 nvidia-*, libnvidia-*, cuda-* and libcudnn*, removes the DKMS source tree and the /opt/nvidia .run installer cache.
• Removes the modules-load config (/etc/modules-load.d/nvidia-vfio.conf) and the nouveau blacklist entries owned by ProxMenux. Legacy two-line ProxMenux blacklist files are migrated and removed too; modified or unrelated administrator files are preserved.
• docs.hardware.nvidiaHost.reinstallUninstall.uninstallItems.3
• Rebuilds initramfs for all kernels, runs proxmox-boot-tool refresh on systemd-boot hosts, and prompts for a reboot to finalise.

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 notifies only when a newer maintenance release exists in the installed branch.

Update message

• Same-branch maintenance. A newer release in your current driver branch (e.g. installed 580.65.06 → available 580.105.08). The Monitor does not infer cross-branch kernel compatibility.

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

Troubleshooting

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).

Related

• 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.