It also documents the specific mistakes that commonly break this install, so you can avoid them.

Applies to: Debian 12 (Bookworm), Optimus laptops with Intel iGPU + NVIDIA dGPU. Examples use an NVIDIA T600 Laptop GPU (Turing, TU117) at PCI address 01:00.0. Adjust the PCI address to match your hardware (find it with lspci | grep -i nvidia).

Before you start: know your starting state

Before installing anything, confirm what the system is actually running. This avoids fighting a half-configured driver. Run:

lspci -k -s 01:00.0                # which kernel driver is bound to the GPU?
lsmod | grep -E 'nvidia|nouveau'   # which modules are loaded right now?
dpkg -l | grep -i nvidia           # any NVIDIA packages already installed?
ls -la /etc/X11/xorg.conf          # is there a leftover X config? (there should NOT be)

On a fresh system you will typically see the open-source nouveau driver bound to the card, no NVIDIA packages installed, and no /etc/X11/xorg.conf. That is the clean baseline this guide assumes.

If /etc/X11/xorg.conf exists, deal with it first. A stale X config — usually left behind by a previous nvidia-xconfig run — is the single most common reason a “clean” reinstall still produces a black screen. Move it out of the way: sudo mv /etc/X11/xorg.conf /etc/X11/xorg.conf.bak. On a PRIME/Optimus laptop you want no hand-written xorg.conf at all.

Step 1 — Enable the non-free repositories

The NVIDIA driver lives in Debian’s non-free component. Check your sources:

cat /etc/apt/sources.list

Each Bookworm line should include contrib non-free non-free-firmware. For example:

deb http://deb.debian.org/debian/ bookworm main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware
deb http://deb.debian.org/debian/ bookworm-updates main contrib non-free non-free-firmware

If your system uses the newer deb822 format instead, you’ll have a .sources file under /etc/apt/sources.list.d/; add contrib non-free non-free-firmware to its Components: line rather than editing sources.list.

Step 2 — Install kernel headers and the driver

The kernel headers are not optional. Without them, DKMS has nothing to build the NVIDIA kernel module against, and the install will silently do nothing — you’ll reboot and still be on nouveau with no obvious error. Install the headers first, then the driver:

sudo apt update
sudo apt install linux-headers-amd64
sudo apt install nvidia-driver mesa-utils

The nvidia-driver metapackage pulls in nvidia-kernel-dkms and builds the module during installation. mesa-utils gives you glxinfo for verification later.

Watch the two messages that appear during install — both are normal and neither is an error. They’re explained next.

“Conflicting nouveau kernel module loaded”

The installer warns that nouveau is currently loaded and conflicts with the NVIDIA module. This is expected: nouveau is driving the card in your running session and can’t be swapped out live. The install adds a modprobe blacklist for nouveau; the switch happens on reboot. Just acknowledge the dialog and let the install finish.

DKMS builds for the current kernel and may “skip” an old one

If you recently ran a system upgrade, you may have more than one kernel installed. DKMS builds the module for your current/newest kernel and may report skipping an older one:

Building for 6.1.0-XX-amd64 6.1.0-YY-amd64
Module build for kernel 6.1.0-XX-amd64 was skipped since the
kernel headers for this kernel do not seem to be installed.
Building initial module for 6.1.0-YY-amd64

This is fine. The module is built for the kernel you’ll actually boot (the newest one). The skipped kernel is just an older fallback entry in GRUB. If you want to silence the skip — for example to keep the fallback kernel bootable with NVIDIA — install headers for that specific version:

sudo apt install linux-headers-6.1.0-XX-amd64   # optional; replace with the skipped version

Step 3 — Reboot and verify

sudo reboot

If the machine comes back up to a normal desktop (no black screen), the Intel-drives-the-display half is already working. Now confirm the driver swap and the offload behavior:

lsmod | grep -E 'nvidia|nouveau'    # want nvidia* loaded, nouveau ABSENT
nvidia-smi                          # want the GPU listed with its driver version
glxinfo | grep "OpenGL renderer"    # want Intel here (desktop on the iGPU = correct)

The desktop renderer reporting Intel is the goal, not a failure. Your everyday desktop should render on the iGPU for battery life. The NVIDIA GPU only comes into play when you explicitly offload to it (next step).

Now prove the NVIDIA GPU wakes on demand:

__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia glxinfo | grep "OpenGL renderer"

This one should report the NVIDIA T600. If it does, PRIME render offload is working end to end.

Step 4 — Using the GPU (offload invocation)

To run any application on the NVIDIA GPU, prefix it with the two offload environment variables:

__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia <application>

For example, to launch a game or a 3D app on the dGPU while everything else stays on Intel. For convenience you can wrap this in a small shell alias or a prime-run-style helper script.

Step 5 — Suspend/resume and power tuning

Debian’s NVIDIA package ships /etc/modprobe.d/nvidia-options.conf with several power-management options present but commented out. Two of them matter on a laptop. Open the file:

sudo nano /etc/modprobe.d/nvidia-options.conf

Uncomment these two lines (remove the leading #):

options nvidia-current NVreg_PreserveVideoMemoryAllocations=1
options nvidia-current NVreg_EnableS0ixPowerManagement=1

Rebuild the initramfs and reboot so the options take effect:

sudo update-initramfs -u
sudo reboot

After the reboot, test a suspend/resume cycle and confirm the display comes back cleanly:

systemctl suspend
# wake the machine, confirm the screen restores correctly

Optional — Fully power down the dGPU when idle

You may notice the NVIDIA GPU stays in a low but non-zero power state even when nothing is offloaded to it:

cat /sys/bus/pci/devices/0000:01:00.0/power/runtime_status   # may read "active"

To have the driver cut power to the GPU entirely (D3cold) when idle, add the aggressive dynamic power-management option as a separate, deliberate change:

echo 'options nvidia "NVreg_DynamicPowerManagement=0x02"' | sudo tee /etc/modprobe.d/nvidia-pm.conf
sudo update-initramfs -u
sudo reboot

After rebooting, re-check runtime_status (you want suspended) and re-test systemctl suspend. D3cold is the one setting most likely to interfere with clean suspend/resume or dGPU wake on some configurations. If anything misbehaves, simply remove the file (sudo rm /etc/modprobe.d/nvidia-pm.conf), rebuild the initramfs, and reboot to revert.

Change one power option at a time and re-test suspend after each. It’s the only reliable way to know which knob caused a regression.

Pitfalls — what not to do

Reference — working configuration summary

Quick verification checklist

# After the full setup, all of these should hold:
lsmod | grep nouveau        # (empty)  -> nouveau blacklisted
nvidia-smi                  # lists the T600 + driver version
glxinfo | grep renderer     # Intel    -> desktop on iGPU
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia glxinfo | grep renderer   # T600
systemctl suspend           # resumes cleanly

This guide was written by Claude, an AI assistant made by Anthropic, based on a hands-on troubleshooting session working through this exact setup step by step.