ProxMenux/web/messages/en/docs/hardware/nvidia-host.json

{
  "meta": {
    "title": "Install NVIDIA Drivers on the Host | ProxMenux Documentation",
    "description": "Install and configure NVIDIA proprietary drivers on a Proxmox VE host using ProxMenux. Covers GPU support filtering, DKMS validation, persistence service, optional NVENC patch and automatic LXC propagation."
  },
  "header": {
    "title": "Install NVIDIA Drivers on the Host",
    "description": "Install the NVIDIA proprietary driver on a Proxmox VE host using ProxMenux. The installer filters maintained branches by GPU PCI ID, validates the selected release through DKMS, manages nouveau, installs the persistence service and can propagate the driver to LXC containers with NVIDIA passthrough.",
    "section": "Hardware: GPUs and Coral-TPU"
  },
  "intro": {
    "title": "What this does",
    "body": "ProxMenux automates the whole NVIDIA driver lifecycle on the host: detects your GPU, offers maintained NVIDIA branches that list its PCI Device ID, blacklists <code>nouveau</code>, downloads and runs the official NVIDIA <code>.run</code> installer with DKMS, installs the <code>nvidia-persistenced</code> service and udev rules, and offers to apply the optional NVENC patch. The DKMS build is the final compatibility check against the running kernel. If you already have LXC containers with NVIDIA passthrough, it can update their userspace libraries to match the host."
  },
  "who": {
    "heading": "Who is this for?",
    "body": "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 <strong>inside an LXC container</strong>, you need to install the driver on the Proxmox <em>host</em> first. This page covers that host-side install. Passing the GPU to a <strong>virtual machine (VM)</strong> uses a different flow (VFIO passthrough) and is documented separately."
  },
  "prereqs": {
    "title": "Before you start",
    "gpu": "<strong>An NVIDIA GPU</strong> physically installed in the host. The script auto-detects it; AMD and Intel GPUs are not handled here.",
    "gpuCheck": "lspci | grep -i nvidia",
    "notVm": "The GPU <strong>is not currently assigned to a VM via VFIO passthrough</strong>. If it is, the script will refuse to install the host driver to avoid breaking the passthrough config.",
    "internet": "Internet access on the host. The installer downloads the driver from <code>download.nvidia.com</code> and, optionally, clones <code>nvidia-persistenced</code> and <code>nvidia-patch</code> from GitHub.",
    "space": "Some free space in <code>/opt/nvidia</code> for the <code>.run</code> installer plus the RAM used during the build. When propagating to LXCs on non-Arch distros, each container needs at least 1.5 GB free; ProxMenux temporarily raises container RAM to 2 GB and restores it after. A reboot is required at the end of the host install."
  },
  "vmWarn": {
    "title": "GPU assigned to a VM? Stop here",
    "body": "If the GPU is currently bound to <code>vfio-pci</code> (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": {
    "heading": "Running the installer",
    "body": "Open ProxMenux on the host, go to <strong>Hardware Graphics → NVIDIA GPU Driver Installer</strong>. What you see depends on whether a driver is already present.",
    "imageAlt": "Hardware Graphics menu with the NVIDIA GPU Driver Installer entry highlighted"
  },
  "howRuns": {
    "heading": "How the script runs",
    "body": "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."
  },
  "walkthrough": {
    "detect": {
      "title": "GPU detection and overview",
      "body1": "The script scans the PCI bus and shows every NVIDIA video controller it finds, the current driver status (or <em>\"No NVIDIA driver installed\"</em>), and any LXC container that already has NVIDIA passthrough configured (driver version inside each one).",
      "body2": "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.",
      "imageAlt": "Pre-install overview showing detected GPUs, current driver status and LXC containers with NVIDIA passthrough"
    },
    "version": {
      "title": "Choose the driver version",
      "body1": "ProxMenux fetches the list of available drivers from NVIDIA and narrows the picker to versions that <strong>list your GPU's PCI Device ID in the supported chips table</strong> of the corresponding branch on <code>nvidia.com</code>. Additional heuristics discard developer / beta CDN drops that would otherwise appear at the top. The first entry is labelled <em>&lt;version&gt; — Recommended</em>: it prefers the head of the branch of the driver already installed on the host (bugfix in place), otherwise the head of the current Production Branch, otherwise the highest supported numeric.",
      "body2": "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.",
      "whyTitle": "How kernel compatibility is validated",
      "whyBody": "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.",
      "imageAlt": "Driver version selector with GPU-supported NVIDIA branches and the Recommended entry on top"
    },
    "uninstall": {
      "title": "Clean uninstall (only if reinstalling)",
      "body": "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 <code>nvidia-*</code> / <code>libnvidia-*</code> / <code>cuda-*</code> packages before touching the new installer. This avoids the classic mixed-version mess."
    },
    "prepare": {
      "title": "Prepare the system",
      "body": "Behind a single confirmation, the script:",
      "items": [
        "Installs <code>pve-headers-$(uname -r)</code> (or <code>proxmox-headers-$(uname -r)</code>), <code>build-essential</code> and <code>dkms</code>.",
        "Creates the ProxMenux-owned <code>/etc/modprobe.d/proxmenux-nouveau-blacklist.conf</code> with <code>blacklist nouveau</code> and <code>options nouveau modeset=0</code>, records whether it added the companion line to <code>blacklist.conf</code>, and tries to unload the module immediately.",
        "Writes <code>/etc/modules-load.d/nvidia-vfio.conf</code> with <code>nvidia</code> and <code>nvidia_uvm</code> so the modules load early at boot."
      ]
    },
    "download": {
      "title": "Download and run the NVIDIA installer",
      "body": "The installer downloads the <code>NVIDIA-Linux-x86_64-&lt;version&gt;.run</code> file into <code>/opt/nvidia</code>, validates it (size + executable signature, not just HTTP 200), then runs it with DKMS so the kernel module rebuilds automatically across kernel upgrades.",
      "imageAlt": "Download progress followed by the NVIDIA installer running its DKMS build"
    },
    "persist": {
      "title": "Persistence service and udev rules",
      "body": "ProxMenux then installs <persistLink>nvidia-persistenced</persistLink> and writes udev rules at <code>/etc/udev/rules.d/70-nvidia.rules</code> so <code>/dev/nvidia*</code> 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."
    },
    "nvenc": {
      "title": "Optional: apply the NVENC patch",
      "body": "Consumer NVIDIA GPUs (GeForce line) limit the number of simultaneous NVENC encoding sessions. The community <patchLink>keylase/nvidia-patch</patchLink> removes that restriction. If you plan to use the GPU for Plex / Jellyfin / Frigate with many concurrent streams, answer <strong>Yes</strong> when prompted.",
      "supportTitle": "Check patch support for your driver",
      "supportBody": "The patch does not cover every driver version. Before relying on it in production, verify your version is listed in the <patchTableLink>patch table</patchTableLink>. If it isn't supported yet, pick a nearby older driver that is."
    },
    "propagate": {
      "title": "Optional: propagate the driver to LXC containers",
      "body1": "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 <strong>must be the exact same version</strong> — otherwise <code>nvidia-smi</code> inside the container will fail with a \"version mismatch\" error.",
      "body2": "The update is distro-aware. For Debian / Ubuntu and other glibc distros, the same <code>.run</code> installer (with <code>--no-kernel-modules --no-dkms --no-install-compat32-libs</code>) is pushed into the container and executed; container RAM is temporarily raised to 2 GB if lower and restored after. For <strong>Arch, Manjaro and EndeavourOS</strong> the update is a <code>pacman -Syu nvidia-utils</code> pinned to the host's driver branch. <strong>Alpine</strong> uses a different path — the <code>.run</code> is extracted on the host, only the userspace libraries are packaged as a tarball and pushed with <code>pct push</code>, then <code>gcompat</code> + <code>binutils</code> shims are installed via <code>apk</code> and SONAME symlinks are recreated with <code>readelf</code> so the glibc-linked libraries load correctly on musl.",
      "imageAlt": "Prompt listing LXCs with NVIDIA passthrough and current driver version, with Yes/No to update them all"
    },
    "reboot": {
      "title": "Reboot",
      "body": "Finally, the script rebuilds <code>initramfs</code> for all kernels and offers to reboot. A reboot <strong>is required</strong>: the nouveau blacklist and the new kernel module only take effect after restart."
    }
  },
  "reinstallUninstall": {
    "heading": "Reinstall or uninstall",
    "intro": "When the installer detects that the <code>nvidia</code> kernel module is currently loaded and <code>nvidia-smi</code> 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.)",
    "imageAlt": "NVIDIA action menu offered when a driver is already installed — two choices: Reinstall / update driver, or Uninstall the NVIDIA driver completely",
    "imageCaption": "The action menu only appears when an NVIDIA driver is currently active on the host.",
    "reinstallHeading": "Reinstall / update",
    "reinstallBody": "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.",
    "uninstallHeading": "Uninstall — what gets removed",
    "uninstallIntro": "Confirms with a yes/no dialog first. Then performs a full, idempotent rollback:",
    "uninstallItems": [
      "Runs <code>nvidia-uninstall --silent</code> first (the counterpart to the <code>.run</code> installer), then stops and disables <code>nvidia-persistenced</code> and <code>nvidia-powerd</code>, and unloads the kernel modules (<code>nvidia_uvm</code>, <code>nvidia_drm</code>, <code>nvidia_modeset</code>, <code>nvidia</code>) — any LXC container with NVIDIA passthrough will be cleanly cut off.",
      "Runs <code>apt purge</code> on <code>nvidia-*</code>, <code>libnvidia-*</code>, <code>cuda-*</code> and <code>libcudnn*</code>, removes the DKMS source tree and the <code>/opt/nvidia</code> .run installer cache.",
      "Removes the modules-load config (<code>/etc/modules-load.d/nvidia-vfio.conf</code>) 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.",
      "Removes the udev rules (<code>/etc/udev/rules.d/70-nvidia.rules</code>) and clears the NVENC patch state (a field in the ProxMenux managed-installs registry, set to <em>removed</em> — no separate file to delete).",
      "Rebuilds <code>initramfs</code> for all kernels, runs <code>proxmox-boot-tool refresh</code> on systemd-boot hosts, and prompts for a reboot to finalise."
    ],
    "lxcWarnTitle": "LXC containers with NVIDIA passthrough",
    "lxcWarnBody": "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."
  },
  "updates": {
    "heading": "Update notifications",
    "body": "The installed NVIDIA driver is tracked in ProxMenux's managed-installs registry. On startup and every 24h the Monitor checks the upstream listing at <code>download.nvidia.com/XFree86/Linux-x86_64/</code> against the version <code>nvidia-smi</code> reports, and notifies only when a newer maintenance release exists in the installed branch.",
    "kindsHeading": "Update message",
    "kindsItems": [
      "<strong>Same-branch maintenance.</strong> 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."
    ],
    "antiTitle": "Anti-cascade by design",
    "antiBody": "One notification per distinct upstream version, never on every 24h scan. If no newer release exists in the installed branch, the tracker stays quiet.",
    "applyTitle": "Applying the update",
    "applyBody": "The Monitor doesn't auto-apply driver updates — reinstalling the NVIDIA driver always needs a reboot. Open the same installer entry described above, pick <strong>Reinstall / update</strong>, and the new version is downloaded, the DKMS module rebuilt against the running kernel, and the reboot prompted at the end."
  },
  "verify": {
    "heading": "Verifying the install",
    "intro": "Once the host is back up, log in over SSH or the Proxmox shell and run:",
    "after": "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:",
    "imageAlt": "Output of nvidia-smi on the host showing the detected GPU and installed driver version"
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "smiFailTitle": "`nvidia-smi` says 'NVIDIA-SMI has failed'",
    "smiFailBody": "Almost always a <strong>nouveau</strong> still loaded or a <strong>kernel header mismatch</strong>. After reboot, run <code>lsmod | grep nouveau</code> — if it returns anything, check <code>/etc/modprobe.d/proxmenux-nouveau-blacklist.conf</code>, rebuild initramfs with <code>update-initramfs -u -k all</code>, and reboot. If nouveau is gone, check <code>dmesg | grep -i nvidia</code> — DKMS build errors usually mean the headers do not match the running kernel.",
    "lxcMissTitle": "LXC container can't see the GPU after host update",
    "lxcMissBody": "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 <code>--no-kernel-modules</code>.",
    "logTitle": "Check the install log",
    "logBody": "Every install writes to <code>/tmp/nvidia_install.log</code>. If something fails silently, that file has the full output (downloads, DKMS build, service installs). Attach it when reporting issues on GitHub."
  },
  "manualSteps": {
    "heading": "Looking for the manual steps?",
    "body": "The original community guide — installing everything by hand with <code>wget</code> and <code>./NVIDIA-Linux-...run</code> — is still available as a reference under <guideLink>Guides → NVIDIA</guideLink>. 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": {
    "heading": "Related",
    "items": [
      {
        "label": "Add GPU to VM (Passthrough)",
        "href": "/docs/hardware/gpu-vm-passthrough",
        "tail": " — pass the NVIDIA GPU to a VM (different binding model from LXC)."
      },
      {
        "label": "Add GPU to LXC",
        "href": "/docs/hardware/igpu-acceleration-lxc",
        "tail": " — share the NVIDIA GPU with one or more containers."
      },
      {
        "label": "Switch GPU Mode (VM ↔ LXC)",
        "href": "/docs/hardware/switch-gpu-mode",
        "tail": " — toggle the same GPU between passthrough (VM) and shared (LXC) modes."
      },
      {
        "label": "ProxMenux Monitor — Hardware tab",
        "href": "/docs/monitor/dashboard/hardware",
        "tail": " — the GPU modal that triggers this installer in one click, plus live monitoring once it's done."
      },
      {
        "label": "GPU Passthrough commands",
        "href": "/docs/help-info/gpu-commands",
        "tail": " — lspci / dmesg / IOMMU / nvidia-smi reference."
      }
    ]
  }
}