Graphics Drivers

Debian Development Machine Setup

Chapter 4 ยท The Graphics Card & Drivers

devserver has an MSI GeForce RTX 3050 LP 6G OC, which is an NVIDIA card, and this chapter gets it working properly. NVIDIA drivers are the one place where a Debian install regularly needs extra work: the good driver is not part of Debian's free software, it has to be compiled against your kernel, and Secure Boot adds a further step. None of it is hard once you know the order, and it is also the chapter where the habit from Chapter 3 (check first, change second) pays off most.

Your Card

The RTX 3050 LP 6G OC is a low-profile, single-slot card built on NVIDIA's Ampere architecture, with 6 GB of GDDR6 memory. MSI lists it as a 70 W card that takes all its power from the PCIe slot, with no separate power connector. That settles the two worries from Chapter 1. It is designed for exactly the kind of low, small-form-factor case you have, and it should not need a bigger power supply or an extra power lead. You should still check that the box includes a bracket that matches your case, and make sure the card is seated firmly.

Plug the monitor into the card
Connect your display to one of the card's outputs, not to the motherboard's own video port. If the motherboard output stays active, the desktop may keep running on the integrated graphics and the card will sit idle.

Two Drivers to Choose From

nouveau (built in)NVIDIA proprietary driver
Comes fromThe Linux kernel and Mesa, developed by the communityNVIDIA, packaged by Debian in the non-free component
SetupWorks with nothing installedEnable non-free, install packages, possibly enrol a Secure Boot key
PerformanceNoticeably lower, especially on newer cardsFull performance
Compute (CUDA and similar)Not availableAvailable
Free software only?YesNo

A development desktop can run happily on nouveau, and if you only need a working screen, that is a fair choice. But you have a 3050 for a reason, and you may one day want CUDA or machine-learning tools, so this chapter installs the proprietary driver. Debian 13 packages the 550 series (550.163.01), which supports Maxwell-generation cards up to Ada and Hopper, so your Ampere card is covered.

Not the newest driver
The 550 series does not support the newest NVIDIA architecture (Blackwell). That does not affect an RTX 3050, but it is worth knowing if you ever swap the card for a very recent one: check driver support first.

Step 1: Check Before You Change

Confirm that Linux can see the card, and find out what it is using now. Also find out whether Secure Boot is on, because that decides whether you need Step 5.

# Is the card visible, and which driver is in use? lspci -k | grep -A3 -i 'vga\|3d' # Is Secure Boot on? (install mokutil first if the command is missing) sudo apt install mokutil mokutil --sb-state # Which kernel are you running? uname -r

In the lspci -k output, look for the line Kernel driver in use:. Right now it is probably nouveau. If lspci shows no NVIDIA device at all, stop: reseat the card, check the BIOS/UEFI setting that chooses the primary display (it may be set to the integrated graphics), and try again. The rest of the chapter assumes the card is detected. mokutil --sb-state prints either SecureBoot enabled or SecureBoot disabled.

Step 2: Enable the non-free Component

Chapter 2 left non-free off on purpose. Now there is a reason to turn it on. Open /etc/apt/sources.list.d/debian.sources and add contrib and non-free to the Components: line of both stanzas, so each reads:

Components: main contrib non-free non-free-firmware

You can make the edit by hand with sudo nano (or sudo vim), or make a backup and let sed change both lines at once:

sudo cp /etc/apt/sources.list.d/debian.sources ~/debian.sources.bak sudo sed -i 's/^Components: .*/Components: main contrib non-free non-free-firmware/' \ /etc/apt/sources.list.d/debian.sources sudo apt update

Afterwards, apt policy nvidia-driver should show a Candidate version. Before this step apt could not find the package at all, because it lives in non-free. That is the Chapter 3 check in action.

Step 3: Install the Driver

sudo apt install linux-headers-amd64 nvidia-kernel-dkms nvidia-driver nvidia-smi
PackageWhat it is
linux-headers-amd64The kernel header files for the current kernel. The driver module is compiled against these.
nvidia-kernel-dkmsThe driver's kernel module, as source that DKMS compiles on your machine. This is the proprietary flavour.
nvidia-driverThe metapackage that pulls in the user-space parts: OpenGL support, the X.org driver, video acceleration.
nvidia-smiA command-line tool that reports what the GPU is doing. It is how you verify the driver later.
What DKMS does
A kernel module has to match the kernel it runs in. DKMS (Dynamic Kernel Module Support) keeps the module's source and rebuilds it automatically every time a new kernel is installed, so the driver keeps working across updates. It needs the matching headers to do that, which is why linux-headers-amd64 is in the list. Installing the driver will take a while because apt compiles the module as part of the install.

Choose the proprietary flavour, not the open one

Debian also offers an open flavour of the module (nvidia-open-kernel-dkms) for newer cards, and your Ampere card would be supported. But the Debian wiki reports that the open flavour of the 550 driver stopped compiling as of kernel 6.12.100, and recommends the proprietary flavour. That is why this chapter installs nvidia-kernel-dkms.

Step 4: Wayland Settings

GNOME on Debian 13 runs on Wayland by default. For NVIDIA cards to work well with Wayland, the driver's nvidia-drm module needs a setting called modeset switched on. Check whether it already is, after the first reboot:

cat /sys/module/nvidia_drm/parameters/modeset

Y means it is on and you need do nothing. If it prints N, the Debian wiki recommends creating /etc/modprobe.d/nvidia-wayland.conf with these two lines:

options nvidia-drm modeset=1 options nvidia-drm fbdev=1

Then run sudo update-initramfs -u and reboot, so the setting is applied early in start-up.

Step 5: Secure Boot and the Machine Owner Key

If mokutil --sb-state said SecureBoot disabled, skip this section. If it said enabled, read on, because the firmware will refuse to load a kernel module that is not signed by a trusted key. Debian signs its own kernel and modules, but a DKMS module is compiled on your machine, so Debian cannot sign it. Instead, DKMS signs it with a key of your own, called a Machine Owner Key (MOK), and you tell the firmware to trust that key once.

DKMS generates the key automatically the first time it builds a module, so the driver install in Step 3 has already created it. Enrol it like this:

# Ask the firmware to trust the key at the next boot; you choose a one-time password sudo mokutil --import /var/lib/dkms/mok.pub # Confirm the request is pending sudo mokutil --list-new sudo reboot

On the reboot, a blue MOK Manager screen appears before Debian starts. Follow its on-screen instructions to enrol the key and enter the one-time password you just chose. This step can only be done at the machine's own keyboard at boot time, which is deliberate: it stops malware running inside Debian from approving its own key. Afterwards you can confirm the key is trusted:

sudo mokutil --list-enrolled
Do not skip the blue screen
If you reboot and miss the MOK Manager prompt, the key is not enrolled, the NVIDIA module will not load, and the desktop may start without acceleration or show a black screen. That is recoverable: switch to a text console with Ctrl+Alt+F3, log in, and run sudo mokutil --import /var/lib/dkms/mok.pub again, then reboot and complete the blue screen. Alternatively, you can turn Secure Boot off in the firmware settings, which avoids the whole step at the cost of that protection.

Step 6: Verify

# Was the module built and installed for the running kernel? dkms status # Is it loaded? lsmod | grep nvidia # Is the driver in use? Expect: Kernel driver in use: nvidia lspci -k | grep -A3 -i 'vga\|3d' # Ask the GPU directly nvidia-smi

dkms status should list an nvidia entry for your kernel with the word installed. nvidia-smi prints a table showing the card's name, the driver version and its memory. If it prints the table, the driver is loaded and talking to the card. If it says it could not communicate with the driver, the module is not loaded: go back to dkms status, and to the Secure Boot step.

Keeping It Working After Kernel Updates

This is the part people forget. A driver that worked yesterday can fail after tomorrow's kernel update. DKMS rebuilds the module for each new kernel, but that build can fail if the driver's source is not yet compatible with the new kernel.

A real example, from the Debian wiki
The Debian wiki records two cases where the 550 driver stopped compiling: the open flavour on kernel 6.12.100, and even the proprietary 550 driver on the 6.19 kernels that reached trixie-backports. The lesson is to stay on Trixie's default kernel, and not to install a newer kernel from backports on this machine unless you have checked that the NVIDIA driver supports it.

A simple routine avoids nasty surprises. After any apt full-upgrade that installs a new kernel, and before you reboot, check that the module was built for it:

# Which kernels are installed? dpkg -l 'linux-image*' | grep ^ii # Is there an nvidia entry marked installed for the NEW kernel? dkms status

If the new kernel has no installed nvidia entry, do not reboot into it yet. The old kernel is still installed and will still work; keep using it until an updated driver arrives.

If Something Goes Wrong

SymptomLikely cause and first step
Card not listed by lspciReseat the card. Check the BIOS/UEFI primary-display setting.
apt policy nvidia-driver cannot find the packagenon-free is not enabled, or you forgot apt update. Recheck Step 2.
The install errors while building the moduleThe headers are missing or do not match the running kernel. Install linux-headers-amd64 and reboot into the current kernel.
Black screen after rebootingSecure Boot key not enrolled, or the module did not load. Use Ctrl+Alt+F3 for a text console.
nvidia-smi: cannot communicate with the driverThe module is not loaded. Check dkms status, lsmod and the Secure Boot state.
Undoing it
If you decide the proprietary driver is more trouble than it is worth, remove it with sudo apt purge nvidia-kernel-dkms nvidia-driver nvidia-smi, then sudo apt autoremove, and reboot. Read apt's list before you confirm, and the machine returns to nouveau. You will have lost nothing but the extra performance.

Hands-On Exercises

Exercise 1

Before changing anything, run the Step 1 checks on devserver and write down: the GPU as lspci reports it, the driver currently in use, the Secure Boot state, and the running kernel. From those four facts, list which of Steps 2–5 you will need to do and which you can skip.

๐Ÿ“„ View solution
Exercise 2

Explain in your own words why a DKMS module cannot be signed by Debian, what a Machine Owner Key is, and why enrolling one requires you to be at the keyboard during boot. Then write the ordered steps to recover if you rebooted and skipped the blue MOK Manager screen.

๐Ÿ“„ View solution
Exercise 3

Write a shell function gpucheck that prints the running kernel, the dkms status lines for nvidia, whether the nvidia module is loaded, and whether nvidia-smi works, and returns a non-zero status if the driver is not healthy. Explain when in your update routine you would run it.

๐Ÿ“„ View solution

Chapter 4 Quick Reference

  • The RTX 3050 LP 6G OC is a low-profile, single-slot Ampere card that draws power from the PCIe slot only (MSI: 70 W, no external connector)
  • Plug the monitor into the card, not the motherboard
  • Debian 13 packages NVIDIA driver 550.163.01; it lives in non-free, so enable contrib non-free in debian.sources
  • Install: sudo apt install linux-headers-amd64 nvidia-kernel-dkms nvidia-driver nvidia-smi
  • Use the proprietary module flavour; the open flavour of 550 fails to compile on newer kernels
  • DKMS recompiles the module for each new kernel and needs the matching headers
  • Secure Boot on? sudo mokutil --import /var/lib/dkms/mok.pub, reboot, complete the blue MOK Manager screen
  • Wayland: cat /sys/module/nvidia_drm/parameters/modeset should print Y
  • Verify with dkms status, lsmod | grep nvidia, lspci -k and nvidia-smi
  • After a kernel update, check dkms status before rebooting; stay on Trixie's default kernel, not backports