How to Install Nvidia Drivers on Debian 11 and 10
If your machine has an NVIDIA GPU but you’re stuck in the old‑school VESA or Mesa modes, this guide will get the proprietary driver up and running on Debian 10 (Buster) or Debian 11 (Bullseye). You’ll see why each step matters and what to watch out for when things go sideways.
1. Prepare Your System
The first thing you want to do is make sure your system isn’t already fighting the driver you’re about to install. Remove any old NVIDIA packages, enable the non‑free repository, and update the package lists.
sudo apt remove --purge '^nvidia-.*' sudo sed -i 's/# deb-src/deb-src/g' /etc/apt/sources.list echo "deb http://deb.debian.org/debian buster contrib non-free" | sudo tee /etc/apt/sources.list.d/nonfree-buster.list # or for Bullseye: echo "deb http://deb.debian.org/debian bullseye contrib non-free" | sudo tee /etc/apt/sources.list.d/nonfree-bullseye.list sudo apt update
Why it matters: If you leave old driver files in place, the new binaries will clash and you’ll end up with a broken X session or even a black screen.
2. Get Kernel Headers and Build Essentials
NVIDIA’s installer compiles parts of itself against your kernel headers. Without them the install will stall.
sudo apt install build-essential dkms linux-headers-$(uname -r)
Why it matters: The driver contains modules that need to be compiled for the exact kernel you’re running. If they can’t find the headers, installation fails.
3. Choose a Driver Version
The Debian repos ship several NVIDIA stacks. Pick one that matches your GPU and your needs:
| Repo | Driver | Notes |
|---|---|---|
| nvidia-driver | Stable (e.g., 470) | Good for most GPUs, supports older cards. |
| nvidia-driver-525 | Newer (e.g., 525) | Latest features, better support for RTX 30‑series. |
Run:
apt-cache search nvidia-driver | grep -E 'driver-[0-9]+$'
I once upgraded to Debian 11 and accidentally installed nvidia-driver-515 on a GPU that only supported up to 410; it worked until I rebooted, then X would not start. Picking the right stack from the get‑go saved me hours of troubleshooting.
4. Install the Driver
With the version decided, install:
sudo apt install nvidia-driver # or a specific one: sudo apt install nvidia-driver-525
During installation, a prompt may ask if you want to copy the nvidia kernel module into /lib/modules. Accept it. The package will also install xserver-xorg-video-nvidia.
Why it matters: Installing via apt guarantees that dkms hooks are set up correctly, so future kernel upgrades automatically rebuild the NVIDIA module.
5. Verify the Installation
Reboot:
sudo reboot
After logging back in, check the driver status:
nvidia-smi
You should see your GPU name, driver version, and usage stats. If it prints “Command not found,” the binaries didn’t make it into /usr/bin. Double‑check that nvidia-utils was installed.
6. Fix Common Problems
| Symptom | Likely Cause | Quick Fix |
|---|---|---|
| Black screen after reboot | Kernel module failed to load | Check dmesg and grep nvidia for errors and make sure the kernel headers match your running kernel. |
| X server crashes on login | Mixed driver modules (Mesa + NVIDIA) | Remove all Mesa “nvidia” drivers: sudo apt purge xserver-xorg-video-nouveau. |
| nvidia-smi reports “Failed to initialize NVML library.” | Incorrect CUDA toolkit version | Ensure the CUDA package matches the driver. Often apt install nvidia-cuda-toolkit will do it. |
I’ve seen a few users install the GPU firmware manually (sudo apt install linux-firmware-nvidia) and then forget to restart, which leaves the driver in a half‑loaded state.
7. Optional: Use nvidia-detect
If you want a quick sanity check before installing, Debian ships a helper script:
sudo apt install nvidia-detect nvidia-detect
It tells you whether your GPU is supported and which package you should pull in. It’s handy when you’re unsure if the card will play nicely with the latest stack.
That’s it—your Debian machine should now be using NVIDIA’s proprietary driver instead of falling back to Mesa or VESA. If you hit a snag, the logs (/var/log/Xorg.0.log, dmesg) are usually very explicit about what went wrong.
