ProxMenux/web/messages/en/docs/hardware/igpu-acceleration-lxc.json

{
  "meta": {
    "title": "Add GPU to LXC | ProxMenux Documentation",
    "description": "Share an Intel, AMD or NVIDIA GPU with an LXC container for hardware-accelerated transcoding (Plex / Jellyfin / Frigate), OpenCL / CUDA workloads, and Mesa video acceleration. ProxMenux handles device nodes, GID alignment, and distro-specific driver install inside the container."
  },
  "header": {
    "title": "Add GPU to LXC",
    "description": "Share one or more GPUs with a Proxmox LXC container. The host keeps using the GPU normally — the container just gets access through device nodes. Works with Intel iGPUs (Quick Sync / VA-API), AMD cards (Mesa / ROCm), and NVIDIA (CUDA / NVENC).",
    "section": "Hardware: GPUs and Coral-TPU"
  },
  "intro": {
    "title": "What this does",
    "body": "Adds <code>dev&lt;N&gt;</code> entries to <code>/etc/pve/lxc/&lt;ctid&gt;.conf</code> for applicable <code>/dev/dri/*</code>, <code>/dev/kfd</code> or <code>/dev/nvidia*</code> nodes. It starts the container, installs userspace packages for its distribution and, for Intel/AMD, aligns the <code>video</code> and <code>render</code> groups. Application acceleration still requires compatible hardware, libraries and app configuration."
  },
  "compare": {
    "heading": "LXC sharing vs VM passthrough",
    "intro": "LXC containers share the host kernel, so they can <em>share</em> the host's GPU without taking it over. That's a big difference from VMs: with <vmLink>VM passthrough</vmLink> the GPU is exclusive to one VM and the host can't use it. With LXC, multiple containers plus the host can all hit the same GPU at once.",
    "headerFeature": "Feature",
    "headerLxc": "LXC (this page)",
    "headerVm": "VM",
    "rows": [
      {
        "feature": "Host keeps using the GPU?",
        "lxc": "Yes",
        "vm": "No — exclusive to the VM"
      },
      {
        "feature": "Multiple containers sharing one GPU?",
        "lxc": "Yes",
        "vm": "No"
      },
      {
        "feature": "Requires IOMMU / VFIO on the host?",
        "lxc": "No",
        "vm": "Yes"
      },
      {
        "feature": "Reboot required?",
        "lxc": "Usually no (just restart the CT)",
        "vm": "When host driver or IOMMU setup changes; not for every VM assignment"
      },
      {
        "feature": "Guest operating systems",
        "lxc": "Only Linux (LXC is Linux-only)",
        "vm": "Supported guest OS with a compatible GPU driver"
      }
    ]
  },
  "prereqs": {
    "title": "Before you start",
    "gpu": "<strong>A GPU on the host</strong> — Intel iGPU, AMD dGPU or APU, or an NVIDIA card. The script auto-detects all three via <code>lspci</code>.",
    "gpuCheck": "lspci | grep -iE 'VGA|3D|Display'",
    "vfio": "<strong>The GPU is NOT bound to vfio-pci.</strong> If the GPU is currently assigned to a VM via passthrough, it's invisible to the host kernel driver and the LXC can't use it. The script detects this and offers to run <switchLink>Switch GPU Mode</switchLink> for you.",
    "nvidia": "<strong>For NVIDIA only:</strong> the NVIDIA host driver must already be installed — ProxMenux needs to match the container's userspace libs to the host version. If you haven't done it yet, run <nvidiaLink>Install NVIDIA Drivers on the Host</nvidiaLink> first.",
    "nvidiaCheck": "nvidia-smi",
    "container": "<strong>An existing LXC container.</strong> The script does not create one. Both privilege modes are supported; a <strong>privileged</strong> container is not universally required. Device entries and the application’s numeric group permissions still need to match."
  },
  "unpriv": {
    "title": "Works on both privileged and unprivileged containers",
    "body": "The script writes <code>dev&lt;N&gt;</code> entries to the LXC config and, on unprivileged containers, aligns the <code>video</code> and <code>render</code> GIDs between host and container so the GPU device nodes are reachable from inside without you having to hand-edit <code>lxc.idmap</code>."
  },
  "running": {
    "heading": "Running the installer",
    "body": "Open ProxMenux on the host, go to <strong>Hardware: GPUs and Coral-TPU → Add GPU to LXC</strong>.",
    "imageAlt": "Menu entry for 'Add GPU to LXC' inside Hardware: GPUs and Coral-TPU"
  },
  "howRuns": {
    "heading": "How the script runs",
    "body": "Select the container and GPU families, then pass the checks. Processing then stops the container and changes its configuration; there is no additional final confirmation. Optional VFIO cleanup has its own confirmation and can change the host earlier."
  },
  "walkthrough": {
    "heading": "Walking through the flow",
    "detect": {
      "title": "Detect host GPUs",
      "body": "The script scans <code>lspci</code> for VGA / 3D / Display controllers matching Intel, AMD or NVIDIA. For NVIDIA it also verifies the <code>nvidia</code> kernel module is loaded and <code>nvidia-smi</code> works — the host driver version it reports will be used to pick the right <code>.run</code> installer for the container.",
      "tipTitle": "NVIDIA not ready?",
      "tipBody": "If NVIDIA is detected but the module isn't loaded, the script won't offer the NVIDIA path. Run <nvidiaLink>Install NVIDIA Drivers on the Host</nvidiaLink> first (and reboot), then come back."
    },
    "pickCt": {
      "title": "Pick an LXC container",
      "body": "Lists eligible LXC containers by ID and name; OCI containers are excluded and use OCI manager Apps for devices. The container is stopped if running, started for driver installation and normally returned to its original running/stopped state.",
      "imageAlt": "Dialog listing existing LXC containers to choose from"
    },
    "selectGpu": {
      "title": "Select the GPU(s) to add",
      "body": "The checklist selects detected vendor families, not an isolated PCI device. Intel/AMD add the visible DRI nodes used by the script; NVIDIA adds its available device nodes, potentially covering multiple cards. One detected family is selected automatically. Verify the resulting device list, particularly on multi-GPU hosts.",
      "imageAlt": "Checklist showing detected GPUs (Intel / AMD / NVIDIA) with vendor and PCI address"
    },
    "preflight": {
      "title": "Pre-flight checks",
      "imageAlt": "Dialog offering to run Switch GPU Mode when the selected GPU is still bound to vfio-pci for VM passthrough",
      "intro": "Three checks, any of which can block or redirect you:",
      "items": [
        "<strong>SR-IOV guard.</strong> This assistant blocks a selected VF or PF with active VFs. That is a limitation of its broad device selection, not a universal prohibition on SR-IOV with LXC; configure those devices separately.",
        "<strong>Bound to vfio-pci.</strong> If the GPU is currently held by VFIO for VM passthrough, the host kernel can't create <code>/dev/dri/*</code> or <code>/dev/nvidia*</code> nodes for it. The script offers to run <switchLink>Switch GPU Mode</switchLink> which undoes the VFIO binding; you'll likely need a reboot before re-running Add GPU to LXC.",
        "<strong>Already configured.</strong> If the container already has every dev node for the selected GPU, the script says so and exits cleanly. If it's partially configured, it continues with only the missing pieces."
      ]
    },
    "applyConfig": {
      "title": "Apply the LXC config changes",
      "body1": "Stops the container if running and edits <code>/etc/pve/lxc/&lt;ctid&gt;.conf</code>. Numbered <code>dev&lt;N&gt;</code> entries carry the host <code>video</code> or <code>render</code> GID. Existing <code>lxc.mount.entry</code> bind lines for <code>/dev/dri</code> are replaced by <code>dev:</code> entries; inspect the resulting configuration and permissions.",
      "body2": "Example after Intel + NVIDIA on the same container:"
    },
    "installDrivers": {
      "title": "Start the container and install drivers inside",
      "body": "Once the config is written, the script starts the container, waits up to ~30 seconds for <code>pct exec</code> to respond, and then detects the container's distro from <code>/etc/os-release</code>. Based on that, it installs the right userspace packages.",
      "headerDistro": "Distro",
      "headerInt": "Intel / AMD",
      "headerNvidia": "NVIDIA",
      "rows": [
        {
          "distro": "Alpine",
          "intel": "apk add mesa-va-gallium intel-media-driver libva-utils",
          "nvidia": "apk add nvidia-utils"
        },
        {
          "distro": "Arch / Manjaro",
          "intel": "pacman -Sy intel-media-driver mesa libva-utils",
          "nvidia": "pacman -Sy nvidia-utils"
        }
      ],
      "debianDistro": "Debian / Ubuntu / others",
      "debianIntel": "apt-get install va-driver-all intel-opencl-icd vainfo",
      "debianNvidia": "extract host <code>.run</code> → <code>pct push</code> → run with <code>--no-kernel-modules --no-dkms</code>",
      "whyTitle": "Why the NVIDIA .run dance on Debian",
      "whyBody": "Repository packages may not match the host driver. Container libraries <strong>must match the loaded host module</strong> for NVML tools such as <code>nvidia-smi</code>. The Debian/glibc path uses the cached host-version <code>.run</code> installer, extracts and packs it on the host, transfers it with <code>pct push</code> and installs with <code>--no-kernel-modules --no-dkms</code>. Alpine and Arch use repository packages, whose versions still need checking."
    },
    "alignGids": {
      "title": "Align GIDs and restore state",
      "body1": "For Intel/AMD, reads the host GIDs for <code>video</code> and <code>render</code>, using 44/104 only as fallbacks, then edits <code>/etc/group</code> inside the container to match; NVIDIA-only runs skip this step. Entries such as <code>video:44</code> and <code>render:104</code> are examples, not universal IDs. Verify app membership and effective device permissions.",
      "body2": "On the normal completion path, a container that was initially stopped is stopped again; one that was running stays running. If startup or installation fails, verify its final state and the log."
    }
  },
  "vendors": {
    "heading": "Vendor-specific notes",
    "intelHeading": "Intel iGPU",
    "intelBody": "Intel media acceleration, including <em>Quick Sync</em>, depends on GPU generation, codecs and app configuration. The script shares whichever of <code>/dev/dri/card0</code>, <code>card1</code>, <code>renderD128</code> and <code>renderD129</code> exist; other node numbers are not added. The host must already provide them through its native driver, for example <code>i915</code>.",
    "amdHeading": "AMD",
    "amdBody": "AMD uses DRI nodes for Mesa/VA-API. If the host exposes <code>/dev/kfd</code>, the script also shares it. ROCm/OpenCL workloads still require supported hardware and compatible userspace packages; sharing the device does not install a complete ROCm stack.",
    "nvidiaHeading": "NVIDIA",
    "nvidiaBody": "Shares available <code>/dev/nvidia*</code> nodes. <strong>Driver-version matching</strong> remains essential for <code>nvidia-smi</code>. Debian/glibc uses the cached host-version <code>.run</code>; Alpine/Arch use repository packages. If the Debian path finds less than 2048 MiB configured RAM, it offers a temporary increase and later restores it; it also requires at least 1500 MiB of free disk space.",
    "updateTitle": "After a host NVIDIA update, check container library versions",
    "updateBody": "Old container libraries can make <code>nvidia-smi</code> report a mismatch. The <nvidiaLink>NVIDIA host installer</nvidiaLink> offers container updates. Re-running Add GPU to LXC may exit when its device entries already exist, so it is not a guaranteed library-refresh command. Check the installed versions and update the appropriate container packages or userspace installer."
  },
  "verification": {
    "heading": "Verification",
    "body": "After the script finishes, log into the container and check the GPU is visible:"
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "mismatchTitle": "nvidia-smi: Failed to initialize NVML: Driver/library version mismatch",
    "mismatchBody": "Container libraries do not match the loaded host module. Inspect versions and update the container userspace appropriately. The cached <code>.run</code> supports the Debian/glibc path, but Add GPU to LXC can exit early when all device entries already exist.",
    "denyTitle": "Permission denied on /dev/dri/renderD128 inside the container",
    "denyBody": "Check the device entry and numeric <code>render</code> group permissions, then whether the app user belongs to <code>render</code>. Where available, add that user to <code>render</code> with <code>usermod -aG render &lt;user&gt;</code>, replacing the placeholder with the actual account. Restart the application session to apply membership; changing privilege mode is not a general permissions fix.",
    "vainfoTitle": "vainfo says: VA-API version 1.xx; failed to initialize",
    "vainfoBody": "Check device access and the selected VA-API driver. Package names vary by distribution: examples include <code>intel-media-driver</code> for supported newer Intel GPUs, <code>i965-va-driver</code> for supported older ones, and <code>mesa-va-drivers</code> for AMD. The message alone does not prove a missing package.",
    "logTitle": "Install log",
    "logBody": "Every run writes to <code>/tmp/add_gpu_lxc.log</code> on the host. Include it when asking for help on GitHub."
  },
  "related": {
    "heading": "Related",
    "items": [
      {
        "label": "Install NVIDIA Drivers (Host)",
        "href": "/docs/hardware/nvidia-host",
        "tail": " — required prerequisite for NVIDIA GPUs before passing them to a container."
      },
      {
        "label": "Add GPU to VM (Passthrough)",
        "href": "/docs/hardware/gpu-vm-passthrough",
        "tail": " — alternative model when you need the GPU dedicated to a single VM."
      },
      {
        "label": "Switch GPU Mode (VM ↔ LXC)",
        "href": "/docs/hardware/switch-gpu-mode",
        "tail": " — toggle the same GPU between LXC sharing and VM passthrough."
      },
      {
        "label": "GPU Passthrough commands",
        "href": "/docs/help-info/gpu-commands",
        "tail": " — quick reference for related shell commands."
      }
    ]
  }
}