Hardware acceleration

Source: lib/hwaccel.func for the container side and pve/backend.func for the host side.

GPU support has two halves that run in different places:

1. On the Proxmox VE host, while the container is created, the engine detects the GPUs and writes their device nodes into the container's config.
2. Inside the container, the install script calls setup_hwaccel, which installs the userspace drivers that match the devices it finds.

lib/hwaccel.func has exactly one public function, setup_hwaccel. Everything else in the file is internal.

Turning it onCopy Anchor Link

Both halves are controlled by one setting, var_gpu. A script whose app benefits from a GPU sets the default in its ct/ file, for example ct/agentdvr.sh:

var_gpu="${var_gpu:-yes}"

The user can override it on the command line (var_gpu=yes or var_gpu=no), in a defaults file, or in the advanced settings dialog "Enable GPU Passthrough?". The engine turns the result into ENABLE_GPU and exports it into the container. setup_hwaccel returns immediately when ENABLE_GPU is no, so calling it in an install script is safe whether or not the user wants a GPU.

What the host passes throughCopy Anchor Link

With var_gpu=yes, pve/backend.func does the following before the container's first start.

Detection. It lists the host's PCI devices of class VGA, XGA, 3D or Display controller. If there are none, nothing is passed through.

An NVIDIA card without /dev/nvidia* nodes is skipped with a warning: the host driver is not loaded.

Selection. One detected type is configured automatically. With several types the host asks which to pass through; the prompt accepts numbers, comma-separated, or A for all, and falls back to all after 60 seconds. With several NVIDIA cards a second prompt of the same kind selects the cards. The shared NVIDIA nodes (nvidiactl, nvidia-uvm*, nvidia-caps/*) are always added.

Config entries. Each selected node becomes a line in /etc/pve/lxc/<CTID>.conf, numbered across all types:

dev0: /dev/dri/renderD128,gid=44
dev1: /dev/dri/card0,gid=44

Group IDs. The gid=44 is a placeholder. After the first start the host reads the container's real video and render group IDs (creating the groups if they are missing), stops the container, rewrites the entries so that renderD* and /dev/kfd belong to render and card* to video, and starts the container again. If that restart fails, the script exits with code 227.

Disk. When an AMD GPU is among the selected types, the root disk is enlarged by 4 GB to make room for ROCm.

Exports. The host exports GPU_TYPE with the configured types, space-separated, for example INTEL NVIDIA. Into the container go ENABLE_GPU and CTTYPE (0 privileged, 1 unprivileged).

setup_hwaccelCopy Anchor Link

Detects the GPUs visible in the container, installs the matching userspace drivers and sets device permissions.

setup_hwaccel [service_user]

HWACCEL_VENDOR is nvidia only when the NVIDIA card turned out to be usable: device nodes present, libcuda.so.1 loadable, and its driver series equal to the host's. Otherwise it is the first Intel or AMD type that was configured, or none. amd_apu is kept apart from amd because an APU gets Mesa only, not ROCm.

Return value. setup_hwaccel has no error code of its own; every exit is a return 0 or the end of the function. Hardware acceleration is optional, so a missing GPU, a missing package or an NVIDIA version mismatch produces a warning and the install continues. Check HWACCEL_VENDOR if the script has to know the outcome. The one step that is not guarded is the apt update after the Debian non-free sources are added: if that fails, the install script's error handler stops the install.

Examples. install/jellyfin-install.sh passes the service user:

setup_hwaccel "jellyfin"

install/audiomuse-ai-install.sh calls it without an argument and then picks its backend from the result:

setup_hwaccel

elif [[ "${HWACCEL_VENDOR:-none}" == "nvidia" ]]; then
  var_backend="gpu"

Step by stepCopy Anchor Link

1. Returns if ENABLE_GPU is no.
2. Returns with a warning if none of /dev/dri, /dev/nvidia0, /dev/kfd exists: no GPU was passed through.
3. Installs pciutils if lspci is missing.
4. Builds the GPU list from lspci (see Detection).
5. Selects which GPUs to configure (see Selection).
6. Installs drivers per GPU type (see the vendor sections).
7. Sets device permissions and group memberships.
8. Exports HWACCEL_VENDOR.

DetectionCopy Anchor Link

lspci inside a container shows the host's whole PCI bus, so the list is filtered to VGA, XGA, 3D and Display controllers and classified by name:

An NVIDIA card that is on the host's bus but has no /dev/nvidia* node in the container is skipped with a notice. If nothing is found and the CPU is not AMD, the function warns and returns.

SelectionCopy Anchor Link

• One GPU: configured without asking.
• Several GPUs of the same type: all configured without asking, since they share one driver stack.
• Several types: a numbered menu. Enter numbers separated by commas, or A for all. After 60 seconds without input, or on invalid input, all are configured.

If an NVIDIA GPU is selected and INSTALL_NVIDIA_DRIVERS is not set, the function asks Install NVIDIA driver libraries in the container? [Y/n] and assumes yes after 60 seconds. With no, the NVIDIA step is skipped and only permissions are set.

IntelCopy Anchor Link

All Intel paths install VA-API drivers and tools through apt. Packages that a release does not carry are skipped with a warning naming them.

Intel OpenCL on Debian depends on the release:

• bookworm: intel-opencl-icd and libigdgmm12 from the Debian repository.
• trixie and sid: the packages are downloaded from the GitHub releases of intel/compute-runtime and intel/intel-graphics-compiler. The compiler version is read from the compute-runtime release notes, because compute-runtime only works with the exact version it was built against. If that version cannot be read, OpenCL is skipped; VA-API still works. These packages are amd64 only.

AMDCopy Anchor Link

ROCm 7.2 is installed for discrete GPUs on amd64 only, from repo.radeon.com: rocm-opencl-runtime, rocm-hip-runtime and rocm-smi-lib. Debian bookworm and Ubuntu jammy use the jammy repository, Debian trixie/sid and Ubuntu noble the noble one; other releases skip ROCm with a warning. The function adds /opt/rocm/bin to PATH through /etc/profile.d/rocm.sh and registers /opt/rocm/lib with the dynamic linker. Kernel drivers are not installed; they belong to the host.

NVIDIACopy Anchor Link

The NVIDIA userspace libraries have to match the kernel module loaded on the host. The function reads the host's driver version from /proc/driver/nvidia/version. If it is not there, only va-driver-all and vainfo are installed.

Debian. It tries NVIDIA's CUDA repositories in an order that depends on the release and uses the first one that carries the host's driver series:

If none does, Debian's own non-free packages are checked last. The exact host version is preferred; otherwise the newest package of the same series is taken and a warning states both versions. The function then installs libcuda1, libnvcuvid1, libnvidia-encode1 and libnvidia-ml1 at that version and writes apt pins to /etc/apt/preferences.d/nvidia-cuda-pin. If no repository has the host's series, nothing is installed and the function says so, rather than installing a newer userspace that cannot work.

Ubuntu. It adds the CUDA repository for 22.04 or 24.04 and installs the same four libraries in the host's driver series. If that fails it tries Ubuntu's own libnvidia-decode-<series>, libnvidia-encode-<series> and nvidia-utils-<series>.

Result check. At the end the function reports one of:

A missing nvidia-smi is reported separately and does not affect CUDA: the CUDA repository ships that package as an empty transitional one.

PermissionsCopy Anchor Link

After the drivers, for every vendor:

• In a privileged container, /dev/dri/* is set to mode 660, the current user is added to video and render, and vainfo is run as a check.
• /dev/nvidia* and /dev/nvidia-caps/* get group video and mode 660.
• /dev/kfd gets group render and mode 660.
• The service_user argument, if given, is added to render and video.

Other platformsCopy Anchor Link

On Incus, incus/tools.func defines its own, smaller setup_hwaccel. The devices are attached when the instance is created; inside it the function only checks that they are visible and sets HWACCEL_VENDOR. Install scripts call it the same way.

Alpine containers load lib/alpine.func, which has no setup_hwaccel.

Internal functionsCopy Anchor Link

These are called by setup_hwaccel. Do not call them from a script.