Skip to content

How To Install NVIDIA Drivers on Bare-Metal Debian

Running hardware-accelerated workloads (like Jellyfin transcoding or AI models) in a bare-metal Kubernetes cluster requires configuring the proprietary NVIDIA kernel drivers directly on the host OS.

Because Debian does not ship pre-compiled NVIDIA drivers for every possible kernel update, it uses DKMS (Dynamic Kernel Module Support) to compile the driver locally. This introduces a few classic pitfalls.

Prerequisites

  • A physical machine with an NVIDIA GPU.
  • Debian installed (e.g., Debian 13 "Trixie").
  • CRITICAL: Secure Boot must be disabled in your motherboard's UEFI BIOS. Secure Boot actively blocks unsigned, third-party kernel modules (like nvidia.ko) from loading. If it is enabled, the driver installation will appear successful, but the GPU will fail to initialize on boot.

Step 1: Enable Non-Free Repositories

Debian strictly separates open-source software from proprietary software. The NVIDIA drivers are proprietary and located in the non-free repository.

Ensure your /etc/apt/sources.list or /etc/apt/sources.list.d/debian.sources contains the contrib, non-free, and non-free-firmware components.

Or, using an Ansible task:

- name: Ensure non-free and contrib repositories are enabled
  ansible.builtin.apt_repository:
    repo: "deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware"
    state: present

Step 2: Install Kernel Headers and Drivers

This is the most common failure point. DKMS requires the C header files for your specific running kernel to compile the module. If you skip installing linux-headers-amd64, DKMS will silently fail to build the driver.

Run the following command to update apt and install the headers alongside the driver:

sudo apt-get update
sudo apt-get install -y linux-headers-amd64 nvidia-driver firmware-misc-nonfree

Note: firmware-misc-nonfree is required for certain modern NVIDIA GPUs to initialize correctly.

Step 3: Verify DKMS Build Status

After the installation completes, verify that DKMS actually compiled the module for your kernel:

sudo dkms status

What to look for: - nvidia-current/550.x.x, 6.1.x-amd64, x86_64: installed -> SUCCESS! - nvidia-current/550.x.x: added -> FAILURE! (This means DKMS extracted the source code but failed to compile it, likely because the kernel headers were missing).

If it says added, ensure linux-headers-amd64 is installed, then force a rebuild:

sudo dpkg-reconfigure nvidia-kernel-dkms

Step 4: Reboot and Verify

Once DKMS says installed, you must reboot the node to load the new kernel module.

sudo reboot

After the node comes back online, run the NVIDIA System Management Interface:

nvidia-smi

You should see a beautiful ASCII table detailing your GPU model, VRAM usage, and driver version. Your physical node is now ready to support GPU containers!