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 detects the GPU and offers maintained NVIDIA branches listing its PCI ID. It blacklists <code>nouveau</code>, downloads the official <code>.run</code> installer, uses DKMS, installs <code>nvidia-persistenced</code>, udev rules and the NVIDIA Container Toolkit, and offers an optional NVENC patch. Build checks assess the running kernel; successful compilation does not guarantee every app works. Existing NVIDIA LXCs are offered a userspace library update, version-matched except on Arch."
  },
  "who": {
    "heading": "Who is this for?",
    "body": "For GPU-accelerated video or compute apps such as Plex, Jellyfin, Frigate, Immich or Stable Diffusion <strong>inside LXC</strong>, install the supported NVIDIA driver on the Proxmox <em>host</em> first. Assigning a GPU directly to a <strong>VM</strong> uses the separate VFIO workflow."
  },
  "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": "Allow disk space in <code>/opt/nvidia</code> for the <code>.run</code> installer and RAM for compilation. The non-Arch LXC update path checks for 1500 MiB free and can request a temporary increase to 2048 MiB RAM if lower, restoring the prior limit afterwards. Plan for the host reboot prompt."
  },
  "vmWarn": {
    "title": "GPU assigned to a VM? Stop here",
    "body": "If any NVIDIA device is bound to <code>vfio-pci</code>, this installer aborts, including when the VM is stopped. A reserved device is not necessarily in active use by a VM. Plan the return to host-driver mode and remove obsolete VM and VFIO assignments before rebooting and installing."
  },
  "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 workflow detects devices, selects a release and performs installation. A separately confirmed stale-VFIO cleanup can occur before the overview. Repository/header preparation and downloading also precede replacement of the existing driver, so there is no single final confirmation after which all changes begin."
  },
  "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 detected GPU and host/container versions before proceeding. Cancel at the overview if the selection is unexpected; any separately confirmed earlier VFIO cleanup has already taken place.",
      "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": "When the installed driver is tracked as NVENC-patched through keylase, the picker narrows to versions listed in the patch table. The <em>Reinstall / update</em> workflow still includes confirmation and patch prompts; check the final patch result.",
      "whyTitle": "How kernel compatibility is validated",
      "whyBody": "The list uses maintained branches and GPU PCI support, rather than a fixed kernel/driver matrix. A pre-build check tests the selected release against the running kernel. A confirmed build failure returns to selection; an unavailable pre-check can produce a warning and continue. Final installation and runtime checks still matter.",
      "imageAlt": "Driver version selector with GPU-supported NVIDIA branches and the Recommended entry on top"
    },
    "uninstall": {
      "title": "Clean uninstall (only if reinstalling)",
      "body": "After downloading and checking the selected installer, an existing driver is removed before replacement. ProxMenux stops NVIDIA services, unloads modules, removes DKMS entries and purges <code>nvidia-*</code> / <code>libnvidia-*</code> / <code>cuda-*</code> packages. This also applies to a confirmed reinstall of the same version."
    },
    "prepare": {
      "title": "Prepare the system",
      "body": "During preparation, the script:",
      "items": [
        "Checks the repositories of the host before anything is removed or installed: a host with no active subscription and only the Enterprise repository is asked before switching to no-subscription, and the installation stops when the switch is declined.",
        "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": "Downloads <code>NVIDIA-Linux-x86_64-&lt;version&gt;.run</code> into <code>/opt/nvidia</code>, checking file size and executable type. These are file-format checks, not cryptographic signature verification. The installer registers DKMS for rebuilds on kernel changes; source and kernel compatibility are still required.",
      "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": "NVENC session limits depend on GPU and driver. The community <patchLink>keylase/nvidia-patch</patchLink> can remove the driver session limit for supported versions. Choose <strong>Yes</strong> only if you need that encoding change and your version is supported. This does not accelerate decoding or remove hardware capacity limits.",
      "supportTitle": "Check patch support for your driver",
      "supportBody": "Check your exact release in the <patchTableLink>patch table</patchTableLink>. If it is missing, keep an unpatched driver or select another maintained release that supports your GPU and kernel as well as the patch; do not choose an older release solely because it is nearby in the list."
    },
    "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": "Debian / Ubuntu and other glibc containers receive the extracted <code>.run</code> installer with <code>--no-kernel-modules --no-dkms --no-install-compat32-libs</code>; RAM can temporarily increase to 2 GiB and is restored afterwards. <strong>Arch, Manjaro and EndeavourOS</strong> use <code>pacman -Syu nvidia-utils</code> from configured repositories, without pinning to the host version: verify the result. <strong>Alpine</strong> receives the extracted <code>.run</code> payload through <code>pct push</code>, installs <code>gcompat</code> and <code>binutils</code> with <code>apk</code>, and builds SONAME links using <code>readelf</code>. Check runtime functionality; compatibility shims do not guarantee every driver library works on musl.",
      "imageAlt": "Prompt listing LXCs with NVIDIA passthrough and current driver version, with Yes/No to update them all"
    },
    "reboot": {
      "title": "Reboot",
      "body": "After the driver installation, the script rebuilds <code>initramfs</code> for all kernels; its last step offers a reboot. <strong>Plan that restart</strong> to verify the persistent module and nouveau configuration on a fresh boot, even when the new driver already responds before reboot."
    }
  },
  "reinstallUninstall": {
    "heading": "Reinstall or uninstall",
    "intro": "If <code>nvidia</code> is loaded and <code>nvidia-smi</code> returns a version, an action menu appears. This identifies an active driver for the menu; driver files can still be installed even when the module is not loaded.",
    "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 through release selection, repository/header preparation, download and pre-build checking before removing the old driver and installing the new one. It can update within a maintained branch or select another supported branch. LXC library and NVENC patch prompts appear again afterwards.",
    "uninstallHeading": "Uninstall — what gets removed",
    "uninstallIntro": "After a yes/no confirmation, the uninstall removes the following driver components:",
    "uninstallItems": [
      "Stops and disables <code>nvidia-persistenced</code> and <code>nvidia-powerd</code>, attempts to unload <code>nvidia_uvm</code>, <code>nvidia_drm</code>, <code>nvidia_modeset</code> and <code>nvidia</code>, then runs <code>nvidia-uninstall --silent</code> for the <code>.run</code> installation. NVIDIA-dependent LXC workloads are affected; active clients can prevent unloading.",
      "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>nvidia-persistenced</code> and <code>nvidia-patch</code> folders under <code>/opt/nvidia</code>.",
      "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 interrupts NVIDIA-dependent LXC workloads, even when their userspace libraries remain installed. Schedule maintenance for Frigate, Plex, Jellyfin, Ollama or other apps that use the GPU."
  },
  "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": "Monitor reports updates without installing them automatically. Open the installer and choose <strong>Reinstall / update</strong>, select a supported version, and complete its build and installation steps. The workflow ends with a reboot prompt; plan the restart and verify the host and LXC libraries afterwards."
  },
  "verify": {
    "heading": "Verifying the install",
    "intro": "Once the host is back up, log in over SSH or the Proxmox shell and run:",
    "after": "Check that your GPU and the expected driver version appear. Processes may already be listed if host services or autostarted containers use the GPU. 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": "Possible causes include <strong>nouveau</strong> claiming the GPU, <strong>missing or mismatched kernel headers</strong>, incompatible driver sources or other module-load errors. Inspect <code>lsmod | grep nouveau</code> and <code>dmesg | grep -i nvidia</code>, plus the installer/DKMS logs. If nouveau policy needs fixing, check <code>/etc/modprobe.d/proxmenux-nouveau-blacklist.conf</code> before rebuilding with <code>update-initramfs -u -k all</code> and rebooting. Do not assume every build error is a header mismatch.",
    "lxcMissTitle": "LXC container can't see the GPU after host update",
    "lxcMissBody": "Check host device nodes, LXC permissions and the driver-library version before reinstalling. A version mismatch can require the matching userspace driver inside the LXC, using the supported distro path; on glibc systems the installer uses <code>--no-kernel-modules</code>. Reinstalling libraries will not repair missing device mounts or permissions.",
    "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": "See <guideLink>Guides → NVIDIA</guideLink> for manual background, including <code>wget</code> and <code>./NVIDIA-Linux-...run</code>. It explains the components but is not an exact transcript of the automated installer. Use the maintained ProxMenux workflow for its GPU filtering, build checks, LXC updates and VFIO 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."
      }
    ]
  }
}