NvidiaGraphicsDrivers - Debian Wiki

Translation(s): English - Español - Français - Русский - 简体中文

This page describes how to install Nvidia's proprietary GPU drivers on Debian systems.

(Note for editors: please turn on the comments visibility and see this Debian forum thread before editing this page)

Note for editors: when modifying the document's structure, please check that references from other sections still make sense and pay special attention to ensure that existing stable-anchor links still work (note that those are often used by other pages.

Those who prefer open source drivers, for security, privacy, or ideological reasons, may want to avoid these drivers and use the open source third-party nouveau driver, although the latter is unfortunately still much less functional and performant than Nvidia's own drivers.

As a consequence of the closed-source nature of the drivers, you should expect compatibility problems, performance problems and general instability problems in certain configurations. If you don't have knowledge to deal with such, you should instead consider AMD or Intel GPUs that come with open-source drivers maintained by their respective manufacturers in the mainline kernel repo, so they work out of the box and no additional steps are required.

Commands in this article prefixed with a $ may be run by normal users, while those with # must be run as root. Switch user to root in your terminal or use sudo as necessary (while this article tries to avoid such situations, remember that in case of commands chained with && or | or ; each sub-command needs to be prefxed with sudo).

As this page has several levels of nested subsections and uses tables, it is recommended to switch to modern theme in preferences section for a better readability (you need to be logged-in).

Want to share feedback about this page? Please join the discussion in this Debian forum thread: improvement suggestions are always welcome! :)

Contents

1. GPU identification
2. Current driver types
   1. Development model and licensing (flavor)
   2. Packaging methods
3. Debian-packaged drivers
   1. Prerequisites
   2. Debian Unstable "Sid"
   3. Debian 13 "Trixie"
   4. Debian 12 "Bookworm"
   5. Debian 11 "Bullseye"
4. Nvidia-packaged data-center drivers
   1. Debian-13 notes
   2. Isolated environments
5. Tesla Drivers
6. Wayland configuration
7. X11 configuration
   1. Single GPU
   2. Multiple GPUs
   3. Displays connected to other GPUs
   4. Other scenarios and resources
8. Optional addons
   1. CUDA
   2. 32bit Intel libs
   3. OptiX
9. Troubleshooting
   1. Installation problems
   2. Operational problems
   3. Where and how to ask the community for help
10. Uninstallation
11. See Also

GPU identification

You can use one of the following ways to check if you have an Nvidia GPU:

Using lspci

$ lspci | grep -iE "3d|display|vga" | grep -i nvidia

A non-empty output (usually a single line) means that an Nvidia GPU is present in the system, for example: 07:00.0 VGA compatible controller: NVIDIA Corporation GM206 [GeForce GTX 960] (rev a1)

Multiple lines indicate multiple Nvidia GPUs. See HowToIdentifyADevice/PCI for more information.

You can also list all types of GPUs in your system: this may be useful for configuring X11 or troubleshooting: $ lspci | grep -iE "3d|display|vga"

Here is an example output on a computer with an Nvidia RTX 3090 and an AMD Strix iGPU: 0b:00.0 VGA compatible controller: NVIDIA Corporation GA102 [GeForce RTX 3090] (rev a1) 65:00.0 Display controller: Advanced Micro Devices, Inc. [AMD/ATI] Strix [Radeon 880M / 890M] (rev c1)

Using nvidia-detect

This script requires installation itself, but it will also recommended which driver to install:

1. Follow apt components section to add non-free component.

2. Install the scipt: # apt install nvidia-detect

3. Finally call the script: $ nvidia-detect

   This should produce output somewhat similar to the below, of course specific details will differ: Detected NVIDIA GPUs: 07:00.0 VGA compatible controller [0300]: NVIDIA Corporation GM206 [GeForce GTX 960] [10de:1401] (rev a1) Checking card: NVIDIA Corporation GM206 [GeForce GTX 960] (rev a1) Your card is supported by all driver versions. Your card is also supported by the Tesla 440 drivers series. Your card is also supported by the Tesla 418 drivers series. It is recommended to install the nvidia-driver package.

Current driver types

Note for editors: there's a LOT of confusion among users regarding driver flavors and packaging methods (see the Nvidia forum for countless examples). This section is intended to build a 3x2 matrix mental-model (packaging*flavor), so that users understand their available options and know where to look for further info. While there are several other aspects how the drivers may be divided into different types, those are much less relevant for an installation or troubleshooting.

Development model and licensing (flavor)

In May 2022 Nvidia announced that starting with version 515 of the drivers, they would move to a more open development model and started publishing source-code for their kernel modules on Github. It is important to note however, that these modules are still tightly coupled with other Nvidia's closed-source components such as firmware and user-space libraries, so as a whole, the driver is definitely not a free software by any means. Since then, each released version is available in two flavors:

• open: based on the mentioned source-code and intended for newer hardware, supports Turing (16xx/2xx) and newer GPUs. Note however that Turing's data-center variant Volta (Titan V, Quadro GV100) is not supported.

• proprietary: based on their older proprietary closed-source code and intended for legacy hardware. It does not support Blackwell (50xx) or newer GPUs.

Packaging methods

There are three major ways that Nvidia drivers are packaged:

• Debian-packaged drivers: these are the most recommended drivers for most users with long-term support (LTS). Other packaging methods should generally only be used in case these drivers cause some problems.

• Nvidia-packaged Unix drivers: these drivers are packaged as distribution-agnostic executable installer files (dot-run). As such they may conflict with other components of a Debian system (see DontBreakDebian). They may be downloaded from Nvidia's archive. See also their deprecation schedule.

• Nvidia-packaged datacenter drivers: despite their name, these drivers do contain desktop components as well, but are mostly intended for compute workloads. They are packaged using distro-specific methods, in case of Debian, Nvidia provided apt repos for Debian versions 10-13.

All 3 types of packaging usually allow to install either open or proprietary flavor for newer versions. Except of issues with Debian packaging itself, problems with all types of Nvidia drivers should generally be reported to Nvidia developer forum. Reports should always include nvidia-bug-report.log.gz file generated using nvidia-bug-report.sh script. Refer to the official guidelines for reporting.

When switching between driver packaging methods, it is critical to first completely purge the previous driver installation before installing the new one. Failure to do so will result in a mix that almost certainly won't work. See Uninstallation section on how to purge Nvidia-packaged DC drivers and Debian-packaged drivers. In case of dot-run installers, you may try --uninstall option, but a complete reinstallation of the OS is more recommended.

Note for editors: as per its official description, package firmware-nvidia-graphics contains firmware for Nouveau driver and is not related to current Nvidia proprietary drivers.

Note for editors: data-center drivers are barely a rolling-release model: in fact there are now apt mechanisms in place to provide a full control over a branch or even a minor version upgrades, so that fleet-update and canary processes may be precisely controlled.

Debian-packaged drivers

Below is the list of available driver versions for each Debian release, together with a brief list of supported GPUs.

Currently no Debian-packaged version supports Blackwell GPUs (for example RTX 50xx series). A wishlist bug has been filed: 1123801. If you have a Blackwell GPU, consider other packaging methods until this is fixed.

Driver versions available for Debian Unstable "Sid": (last updated: 2025-12-16)

• 550.xx.yy series: supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs (the full list of supported devices).

• Version 390.157: legacy driver for Fermi and Kepler GPUs (the full list of supported devices).

• Version 340.108: legacy driver for G8x, G9x, and GT2xx series GPUs (the full list of supported devices).

Driver versions available for Debian 13 "Trixie": (last updated: 2025-12-15)

• 550.xx.yy series: supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs (the full list of supported devices).

• 550.xx.yy series from Backports: the variant of the above patched to work with kernels from trixie-backports.

Driver versions available for Debian 12 "Bookworm": (last updated: 2025-12-16)

• 535.xx.yy series supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs (the full list of supported devices).

Driver versions available for Debian 11 "Bullseye": (last updated: 2025-12-16)

• Version 470.256.02 supports Kepler, Maxwell, Pascal, Turing, and Ampere GPUs. (the full list of supported devices).

Prerequisites

apt components

Make sure that components contrib, non-free and non-free-firmware are enabled at least for the base (bookworm, trxie, fortky etc) and -security suites in your /etc/apt/sources.list file. For example for Trixie you should have at least entries similar to the two below: (the order of components does not matter) deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware deb http://security.debian.org/debian-security/ trixie-security contrib non-free main non-free-firmware

...and often also for -updates: deb http://deb.debian.org/debian/ trixie-updates non-free-firmware non-free contrib main

If any entry in /etc/apt/sources.list related to the official Debian suites (like trixie, trixie-security in case of Trxie and possibly also trixie-updates and trixie-backports if you use them) misses any of the mentioned components, append them accordingly.

If you have corresponding deb-src entries configured, it is recommended to add the components to them as well.

Afterwards run # apt update

This will fetch information about the new components from remote Debian repositories.

You can see SourcesList for more information on configuring apt sources.

Kernel headers

In standard cases you can just ask apt to install linux-headers-generic virtual package and it will pick the right blend for you: # apt install linux-headers-generic

This will install for example linux-headers-amd64 if you have an AMD/Intel CPU or linux-headers-arm64 if you have an ARM CPU.

If you use some special features kernel like -rt or -cloud, you may need to manually point the corresponding -rt/-cloud headers instead of the standard ones mentioned above: # apt install linux-headers-rt-amd64

ToDo: verify if apt cannot figure that out via linux-headers-generic.

SecureBoot

If you have SecureBoot enabled, you need to enroll your machine owner's key (MOK) to use DKMS modules. Detailed instructions are available here. It's recommended to do this before installing nvidia-driver so that you do not have to rebuild the kernel modules.

dracut

If your system uses dracut, you must tell dracut to include modprobe configuration files:

• Make a dracut configuration file /etc/dracut.conf.d/10-nvidia.conf (you can actually name it anything you like, as long as it ends in .conf) with the following contents: install_items+=" /etc/modprobe.d/nvidia-blacklists-nouveau.conf /etc/modprobe.d/nvidia.conf /etc/modprobe.d/nvidia-options.conf "

• Note the spaces between quotes and characters.

• The modprobe.d files referenced here will be added by the nvidia-driver package.

Backports (optional)

Certain version ranges of the driver and of the kernel are tightly coupled with each other (for example "vanilla" drivers older than v580 will not compile on kernels 6.16+). Therefore if you use a kernel from Backports, then you usually need to install a driver from Backports as well and vice-versa.

To prepare your system for installing a driver from Backports, follow the below steps:

1. All 4 components (main, contrib, non-free and non-free-firmware) need to be enabled for the -backports suite, for example for Trixie make sure you have an entry similar to the below in some file in /etc/apt/sources.list.d/ folder, for example in /etc/apt/sources.list.d/backports.list: deb http://deb.debian.org/debian/ trixie-backports main contrib non-free non-free-firmware

   (for other Debian versions replace trixie-backports appropriately with bookworm-backports or bullseye-backports etc).

   If you already have a deb-src entry for the -backports suite, add the components to it as well.

   Note: while it is not recommended, it may happen that -backports suite entries are already configured directly in /etc/apt/sources.list file: in such case you may edit the list of components there or move them somewhere into /etc/apt/sources.list.d/ folder.

2. Update apt's DB: # apt update

3. Install a kernel and its headers from Backports: (replace trixie-backports appropriately with your release) # apt install -t trixie-backports linux-headers-generic In most standard cases this should pick the right headers blend and install the corresponding kernel as their dependency.

   If you use some special features kernel, you may need to specify packages manually as described above in Kernel headers section.

4. If you use any firmware-* packages, you should upgrade them to versions from -backports as well. First get the list of installed ones: $ apt list --installed 'firmware-*'

   This will output a list in a format like the below: firmware-amd-graphics/stable,now 20250410-2 all [installed] firmware-iwlwifi/stable,now 20250410-2 all [installed]

   Review your list and assuming it's non-empty, supply the package names from the fist column to the next command: (replace trixie-backports...) # apt install -t trixie-backports firmware-amd-graphics firmware-iwlwifi

32bit Intel apps support (optional)

If you intend to run 32bit Intel GUI apps (for example most Windows games via Wine or Steam), it is recommended to enable i386 architecture before installing the driver: this way 32bit libs will be automatically pulled at least on all 535+ versions: # dpkg --add-architecture i386 # apt update

Debian Unstable "Sid"

550.xx.yy series

This version series supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs, it does not support Blackwell (the full list of supported devices). For Blackwell consider other packaging methods.

1. Choose a flavor to install:

   • To install the proprietary flavor, packages nvidia-kernel-dkms and nvidia-driver should be installed: # apt install nvidia-kernel-dkms nvidia-driver

   • To instead install the open flavor, packages nvidia-open-kernel-dkms and nvidia-driver should be installed: (reminder: Maxwell, Pascal and Volta GPUs are not supported by this flavor) # apt install nvidia-open-kernel-dkms nvidia-driver

   DKMS will build the modules for your system from either nvidia-kernel-dkms or nvidia-open-kernel-dkms package.

2. Proceed to post-installation steps.

Version 390.157

This version supports Fermi, Kepler, Maxwell and most Pascal GPUs (the full list of supported devices)

Warning: this driver is no longer maintained.

It is recommended to use the built-in Nouveau driver instead.

1. Install the nvidia-legacy-390xx-driver package, plus the necessary firmware: # apt install nvidia-legacy-390xx-driver firmware-misc-nonfree

   DKMS will build the nvidia module for your system, via the nvidia-legacy-390xx-kernel-dkms package.

2. Proceed to post-installation steps.

Version 340.108

This is the last version that supports G8x, G9x, and GT2xx series GPUs (the full list of supported devices).

WARNING: Use of the 340-series driver is strongly discouraged!

It is no longer maintained, has serious unfixable security vulnerabilities and may not be updated for new kernels. You are highly recommended to use the built-in Nouveau driver if security is a priority.

1. Install the nvidia-legacy-340xx-driver package, plus the necessary firmware: # apt install nvidia-legacy-340xx-driver firmware-misc-nonfree

   DKMS will build the nvidia module for your system, via the nvidia-legacy-340xx-kernel-dkms package.

2. Proceed to post-installation steps.

Post-installation steps for Sid

1. Optionally verify the result of the DKMS module compilation: # dkms status |grep nvidia

   This should result in 1 or more lines (1 per each installed kernel version) similar to the below: (the exact versions may differ) nvidia/550.163.01, 6.12.57+deb13-amd64, x86_64: installed

   Anything other than installed at the end means there was some problem: see Troubleshooting section in such case.

2. In most cases a restart of the system is recommended to fully load the new driver.

Debian 13 "Trixie"

550.xx.yy series

This version series supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs, it does not support Blackwell (the full list of supported devices). For older devices, use nouveau, which should be already installed and in use. For Blackwell consider other packaging methods.

Note: this version will not work with kernels 6.16 or newer like the current one from trixie-backports: use the the corresponding version from trixie-backports instead.

1. Choose a flavor to install:

   • To install the proprietary flavor, packages nvidia-kernel-dkms and nvidia-driver should be installed: # apt install nvidia-kernel-dkms nvidia-driver

   • To instead install the open flavor, packages nvidia-open-kernel-dkms and nvidia-driver should be installed: (reminder: Maxwell, Pascal and Volta GPUs are not supported by this flavor) # apt install nvidia-open-kernel-dkms nvidia-driver

   DKMS will build the modules for your system from either nvidia-kernel-dkms or nvidia-open-kernel-dkms package.

2. Proceed to post-installation steps.

550.xx.yy series from Backports

This is a variant of the above 550.xx.yy that was patched to work with kernels from trixie-backports.

1. Prepare the system according to Backports section.

2. Choose a flavor to install:

   • To install the proprietary flavor, packages nvidia-kernel-dkms and nvidia-driver should be installed: # apt install -t trixie-backports nvidia-kernel-dkms nvidia-driver

   • To instead install the open flavor, packages nvidia-open-kernel-dkms and nvidia-driver should be installed: (reminder: Maxwell, Pascal and Volta GPUs are not supported by this flavor) # apt install -t trixie-backports nvidia-open-kernel-dkms nvidia-driver

   DKMS will build the modules for your system from either nvidia-kernel-dkms or nvidia-open-kernel-dkms package.

3. Proceed to post-installation steps.

Post-installation steps for Trixie

1. Optionally verify the result of the DKMS module compilation: # dkms status |grep nvidia

   This should result in 1 or more lines (1 per each installed kernel version) similar to the below: (the exact versions may differ) nvidia/550.163.01, 6.12.57+deb13-amd64, x86_64: installed

   Anything other than installed at the end means there was some problem: see Troubleshooting section in such case.

2. In most cases a restart of the system is recommended to fully load the new driver.

Debian 12 "Bookworm"

535.xx.yy series

This version series supports Maxwell, Pascal, Volta, Turing, Ampere and Ada/Hopper GPUs, it does not support Blackwell (the full list of supported devices). For older devices, use nouveau, which should be already installed and in use. For Blackwell consider other packaging methods.

1. Choose a flavor to install:

   • To install the proprietary flavor, packages nvidia-driver and firmware-misc-nonfree should be installed: # apt install nvidia-driver firmware-misc-nonfree

   • To instead install the open flavor:

     1. Make sure you understand the limitations mentioned in the README (most importantly Maxwell, Pascal and Volta GPUs are not supported by this flavor).

     2. In case of most cards, param NVreg_OpenRmEnableUnsupportedGpus must be set to 1 in somewhere in /etc/modprobe.d/ folder, for example in /etc/modprobe.d/nvidia-open.conf file: options nvidia NVreg_OpenRmEnableUnsupportedGpus=1

     3. Package nvidia-open-kernel-dkms must be additionally installed: # apt install nvidia-open-kernel-dkms nvidia-driver firmware-misc-nonfree

   DKMS will build the modules for your system from either nvidia-kernel-dkms or nvidia-open-kernel-dkms package.

2. Optionally verify the result of the DKMS module compilation: # dkms status |grep nvidia

   This should result in 1 or more lines (1 per each installed kernel version) similar to the below: (the exact versions may differ) nvidia/550.163.01, 6.12.57+deb13-amd64, x86_64: installed

   Anything other than installed at the end means there was some problem: see Troubleshooting section in such case.

3. Nvidia drivers are notorious to misbehave during suspend/hibernate/resume, so the related systemd services are disabled by default. To enable them, issue the following commands: # systemctl enable nvidia-suspend.service # systemctl enable nvidia-hibernate.service # systemctl enable nvidia-resume.service

4. In most cases a restart of the system is recommended to fully load the new driver.

Debian 11 "Bullseye"

Version 470.256.02

This version supports supports Kepler, Maxwell, Pascal, Turing, and Ampere GPUs. (the full list of supported devices).

Note: this driver is no longer maintained.

1. Install the nvidia-driver package, plus the necessary firmware: # apt install nvidia-driver firmware-misc-nonfree

   DKMS will build the nvidia module for your system, via the nvidia-kernel-dkms package.

2. Optionally verify the result of the DKMS module compilation: # dkms status |grep nvidia

   This should result in 1 or more lines (1 per each installed kernel version) similar to the below: (the exact versions may differ) nvidia/550.163.01, 6.12.57+deb13-amd64, x86_64: installed

   Anything other than installed at the end means there was some problem: see Troubleshooting section in such case.

3. Restart your system to load the new driver.

Nvidia-packaged data-center drivers

These drivers are intended mostly for compute workloads, but they do contains all the desktop components as well. It is important to note nevertheless, that releases of fixes or new features to desktop components may lag and are usually delayed until something related to compute needs to be released. Nvidia publishes these drivers in distro-specific ways, in case of Debian apt repos for Debian versions 10-13 are provided, but not all of these versions are still supported: refer to the table below:

(last updated: 2026-02-27)

Debian version	currently supported	released driver versions	flavor support (proprietary / open)	supported GPU archs	supported CUDA versions
10	no	455 - 555	yes / no	Kepler to Ampere with v470 (LTS); Maxwell to Ada/Hopper with later versions	11, 12
11	no	495 - 560	yes / only v560	Maxwell to Ampere with early versions; Maxwell to Ada/Hopper with later versions	11, 12
12	yes	545 - onwards	yes / from v560	Maxwell to Blackwell with v580 (LTS); Turing (but not Volta), Ampere, Ada/Hopper, Blackwell with v590+	12, 13
13	yes	590 - onwards	yes / yes	Turing (but not Volta), Ampere, Ada/Hopper, Blackwell	13

Refer to the official guide regarding installation and usage instructions. For news and updates consider tracking this thread on the Nvidia forum.

To install CUDA toolkit on top of the DC drivers, follow this official guide.

Debian-13 notes

• While the Introduction section of the official documentation mentions Debian-13 as supported, the Debian instructions section only mentions Debian-12. These instructions however do work on Debian-13 as well, just use debian13 as a value for ${distro} and add contrib component manually as add-apt-repository is not present on Trixie by default.

• v590+ does not support Maxwell, Pascal nor Volta GPUs, but several users reported, that drivers v570-580 from the Debian-12 repo worked well with Debian-13.

  Note: since 2026-02-01, Debian-13 rejects signatures using SHA1 used in the NV D-12 repo. To workaround it, you can add --allow-insecure-repositories option to to apt update command. After that apt will ask for explicit confirmation before downloading any package from the insecure repo.

Isolated environments

Nvidia also provides their apt repos packaged as local files to ease up installations in isolated environments. These can be downloaded from the following locations: (choose deb local as Installer Type)

• latest driver

• latest CUDA toolkit together with the driver

• older driver versions archive

• older CUDA toolkit versions archive

Follow the same official driver and CUDA toolkit installation guides as mentioned above.

Tesla Drivers

ToDo: this section probably should be merged into #debian-drivers: clarify with maintainers.

The NVIDIA line-up of programmable "Tesla" devices, used primarily for simulations and large-scale calculations, also require separate driver packages to function correctly compared to the consumer-grade GeForce GPUs that are instead targeted for desktop and gaming usage.

In Debian 10/Buster, the default nvidia-driver package is based on the Tesla release. This was done in order to resolve several critical security issues, but it means that there is no need to install the separate package for Tesla devices to work. If you need a newer release, the 450-series driver is available in backports via the nvidia-tesla-450-driver package.

In Debian 11/Bullseye, the major 418, 440, and 450 releases of the Tesla driver are available and distinct from the default driver. They can be found in the nvidia-tesla-418-driver, nvidia-tesla-440-driver, and nvidia-tesla-450-driver packages respectively.

In Debian 12/Bookworm, the 470 release of the Tesla driver is available in the nvidia-tesla-470-driver package.

The 32-bit libraries can be obtained by installing nvidia-tesla-418-driver-libs:i386, nvidia-tesla-440-driver:i386, or nvidia-tesla-450-driver:i386 based on the version of your driver. Multiarch must be enabled.

Wayland configuration

Wayland is a project aiming to replace X11. Gnome uses it by default on systems using any open-source graphic driver. In case of the NV proprietary driver, specific kernel module options need to be enabled and even then it may not function properly on certain hardware configurations (in which case Gnome will automatically fallback to X11).

The following options need to be enabled:

• NVreg_PreserveVideoMemoryAllocations for nvidia module: command $ grep PreserveVideoMemoryAllocations /proc/driver/nvidia/params

  should output PreserveVideoMemoryAllocations: 1

• modeset for nvidia_drm module: command # cat /sys/module/nvidia_drm/parameters/modeset

  should output Y.

• fbdev for nvidia_drm module: command # cat /sys/module/nvidia_drm/parameters/fbdev

  should output Y.

In case of Nvidia-packaged drivers v580+, all these options are enabled by default.

In case of Debian-packaged drivers, it is usually sufficient to create a file with the following contents somewhere in /etc/modprobe.d/ folder, for example in /etc/modprobe.d/nvidia-wayland.conf file: options nvidia NVreg_PreserveVideoMemoryAllocations=1 options nvidia-drm modeset=1 options nvidia-drm fbdev=1

As of Bookworm, NV modules are not included in initramfs, so there's no need to add the above options to the kernel command line in the GRUB config.

Warning: enabling NVreg_PreserveVideoMemoryAllocations will cause the driver to malfunction on laptops with Optimus hybrid graphics.

X11 configuration

Note: in the reminder of this section, any identifier starting with My may be changed to whatever name you like, you just need to change its other occurances accordingly.

Single GPU

If Nvidia is the only single GPU in your system and the driver is functioning properly, X11 should be able to auto-configure itself without any help.

If that's not the case, you may add a Device entry in some file in /etc/X11/xorg.conf.d/ folder, for example in /etc/X11/xorg.conf.d/20-nvidia.conf file: Section "Device" Identifier "My Nvidia GPU" Driver "nvidia" EndSection

Multiple GPUs

If you have multiple GPUs in your system (Nvidia or others), you may need to point the GPU with its PCIe bus ID: Section "Device" Identifier "My Nvidia GPU" Driver "nvidia" BusID "PCI:11:0:0" EndSection

Bus ID may be obtained from the output of lspci: numbers from the first column need to be converted from hexadecimal to decimal and separated with colons, so 0b:0.0 from the example output becomes 11:0:0 in the config above.

In some situations you may instead decide to run X11 on another GPU and use the Nvidia one to offload only certain tasks: see PRIME offloading section in the driver's README. It is for example common on laptops to run X11 on iGPU for power-saving reasons. In such case AutoAddGPU server flag should be set to false to prevent X11 from autoconfiguring any Nvidia or other cards not configured explicitly: Section "ServerFlags" Option "AutoAddGPU" "false" EndSection Section "Device" Identifier "My AMD iGPU" Driver "amdgpu" BusID "PCI:101:0:0" EndSection

Note that when AutoAddGPU is false, then xrandr --listproviders will not show any other GPUs, but PRIME offloading will still work as long as the kernel driver is functioning properly.

Displays connected to other GPUs

If you have multiple GPUs in your system and want to also use displays connected to those other than the Nvidia one (like for example your laptop's internal display connected to the iGPU), then you usually need to configure those as well (in some cases X does auto-configure everything reasonably well, but often it's not even exactly obvious what the best config is in a given situation). For example in case of the example output in lspci section, you could use the following config:

In /etc/X11/xorg.conf.d/20-nvidia.conf file: Section "Device" Identifier "My Nvidia GPU" Driver "nvidia" Option "AllowEmptyInitialConfiguration" "true" BusID "PCI:11:0:0" EndSection

Option AllowEmptyInitialConfiguration tells nvidia driver to ignore the fact that no displays may be connected to a given GPU. Depending on the driver version, it may refuse to start otherwise. See the official list of recognized options for details.

In /etc/X11/xorg.conf.d/20-amd.conf file: Section "Device" Identifier "My AMD iGPU" Driver "amdgpu" BusID "PCI:101:0:0" EndSection

In /etc/X11/xorg.conf.d/70-screen.conf file: Section "Screen" Identifier "My dual GPU screen" Device "My Nvidia GPU" GPUDevice "My AMD iGPU" EndSection

The Screen section tells X to use My Nvidia GPU as the main GPU performing rendering and My AMD iGPU as an additional one only providing more displays. If you have more GPUs in your system you can add them also as a GPUDevice in your Screen config.

Other scenarios and resources

• If you use your Nvidia card as an eGPU, check the relevant subsection on eGPU page.

• Additional configuration information is available.

Optional addons

CUDA

This section refers to Debian-packaged CUDA toolkit. If you use Nvidia-packaged DC drivers you also need to use Nvidia-packaged tookit by following the official installation guide.

To install CUDA toolkit (nvcc, libs, headers, profilers etc) run the following command: # apt install nvidia-cuda-dev nvidia-cuda-toolkit

Below are the currently available versions:

(last updated: in times before the light...)

Debian version	CUDA version
unstable "Sid"	12.4.127
13 "Trixie"	12.4.127
12 "Bookworm"	11.8.89
11 "Bullseye"	11.2.2

32bit Intel libs

If you didn't configure 32bit support before installing the driver, but decided later you needed it, you can add the support anytime later:

1. Add 32bit sources to apt: # dpkg --add-architecture i386 # apt update

2. Install 32bit version of the NVIDIA libraries: # apt install nvidia-driver-libs:i386

Note: If you're forced to use a legacy driver, you will need to instead install one of nvidia-legacy-390xx-driver-libs:i386, nvidia-legacy-340xx-driver-libs:i386 etc.

OptiX

ToDo: this is probably necessary only on legacy driver versions if at all. Current versions include the below libs by default

To enable NVIDIA OptiX™ Ray Tracing Engine it is necessary to install an additional library: # apt install libnvoptix1

A specific version is available for Tesla cards. # apt install libnvidia-tesla-nvoptix1

Troubleshooting

Installation problems

Package dependency problems

Symptoms:

apt install command output contains a text similar to the following: Solving dependencies... Error! Some packages could not be installed. This may mean that you have requested an impossible situation or if you are using the unstable distribution that some required packages have not yet been created or been moved out of Incoming. The following information may help to resolve the situation: The following packages have unmet dependencies:

Possible reasons and resolutions:

This is usually due to apt sources misconfiguration:

• Make sure that you've added necessary components as described in apt components section.

• If you are trying to install a driver from Backports, check sources configuration in Backports section. After that repeat the apt install command and resume the installation procedure.

• If you have or previously had some packages from Backports or Sid installed and now you are trying to install a driver from the base suite, it is possible, that apt is confused by too high versions of some of your (remaining) installed packages: either downgrade all packages to the base suite or install a driver from Backports/Sid.

Kernel modules build skipped

Symptoms:

apt install command output contains a text similar to the following: (kernel version will likely differ) WARNING: No kernel headers were found, skipping module build. To get the headers for the running kernel (6.17.11+deb14-amd64) please install the linux-headers-6.17.11+deb14-amd64 package.

Possible reasons and resolutions:

This is due to missing kernel headers appropriate for your kernel. Make sure that you have the right headers installed as described in Kernel headers section. Also the above output provides a hint, but for the exact kernel version you are currently running, so it may stop working break after a system upgrade. Generlize the hint by removing the version from the suggested package name, so in this case change linux-headers-6.17.11+deb14-amd64 to linux-headers-amd64 and install it:# apt install linux-headers-amd64

This will often trigger the module build process right away, but sometimes you may need to reconfigure the kernel modules package with one of the following commands:

• in case you are trying to install a proprietary flavor: # dpkg-reconfigure nvidia-kernel-dkms

• in case you are trying to install a Debian-packaged open flavor: # dpkg-reconfigure nvidia-open-kernel-dkms

• to make it more fun (please kill me), in case you are trying to install an Nvidia-packaged open flavor, the package name is slightly different: # dpkg-reconfigure nvidia-kernel-open-dkms

After that resume the installation procedure.

Kernel modules build failures

Symptoms:

apt install command output contains a text similar to the following: (kernel and driver versions will likely differ) Building module(s).........(bad exit status: 2) Failed command: 'make' -j24 modules KERNEL_UNAME=6.17.12+deb14-amd64 NV_VERBOSE=1 Error! Bad return status for module build on kernel: 6.17.12+deb14-amd64 (x86_64) Consult /var/lib/dkms/nvidia/575.57.08/build/make.log for more information.

Possible reasons and resolutions:

1. You've installed a kernel from backports without installing the NVIDIA driver from backports. This can, in some cases, mean that the kernel is too new for the driver version you're attempting to use. Check this by viewing the package description for the NVIDIA driver where it will mention something along the lines of, "Building the kernel module has been tested up to Linux X.X" to figure out what's supported.

2. Particularly if you're on Debian Testing or Debian Unstable, the driver might not support your kernel yet. Often, new versions of the Linux kernel will explicitly require an update to the driver in order to be supported, so if the kernel package updates before the driver has a chance to be patched for it, you won't be able to use the NVIDIA driver. Solutions for this, from most to least recommended, are temporarily using an older kernel until the driver is updated, installing a newer version of the driver from Debian Experimental if one is available that supports your kernel version, or finding a patch for the build failure online that can be added to DKMS. The last two options are for advanced users and may break your system or, in the case of adding a third-party patch, introduce security issues, forcing you to potentially reinstall completely or spend hours recovering your system. Caveat emptor.

3. Legacy versions of the NVIDIA driver may not always support the latest kernel. For instance, the 304xx series driver, though available in the Debian Unstable

repository, does not support Linux 5.0 or newer. As necessary, you might consider using an older Debian version, or using Nouveau instead. Nouveau has decent performance with GPUs that are old enough to no longer be supported by the proprietary driver.

Operational problems

Black screen right after boot menu

ToDo: explain:

1. hot to try to switch to a text console
2. how to check all outputs for signal
3. how to use GRUB to boot to text mode and proceed to the next section.

Nvidia graphics don't work but a text terminal or iGPU graphics available

ToDo: explain:

1. how to check for SecureBoot problems

2. how to check for conflicts with Nouveau
3. how to check for unsupported GPUs symptoms

4. critical module params like modesetting and fbdev

5. in what order to try other flavors and versions

Nvidia graphics works, but with problems

ToDo: explain:

1. most common related module params
2. in what order to try other flavors and versions
3. How to check Nvidia forum version-feedback threads

Driver stops working after upgrading Debian

When going between two major Debian releases (e.g., upgrading from Debian 9/Stretch to Debian 10/Buster), it's possible that the driver will stop functioning despite the build succeeding and no other issues being easily visible. This is most often caused by the nvidia-driver package updating to a newer major release that no longer supports your hardware, as NVIDIA regularly drops support for older hardware generations. You will need to uninstall all your existing NVIDIA packages (refer to the section below for instructions on how to do so), and instead install the most recent legacy driver that still supports your GPU.

Miscellaneous

• The NVIDIA driver conflicts with the nouveau DRM driver (580894). The nouveau kernel module is blacklisted by the glx-alternative-nvidia or nvidia-kernel-common packages.

  • Restart your system after configuring Xorg for the NVIDIA driver.

  • From xserver-xorg-video-nouveau's README.Debian: If you decide to switch to the proprietary driver, it is highly recommended to reboot because it is incompatible with nouveau, and unloading the latter is not easy and may lead to a blank console.

• If you can't change the screen brightness, open your Xorg configuration file (/etc/X11/xorg.conf or /etc/X11/xorg.conf.d/20-nvidia.conf depending on which method you used) and add Option "RegistryDwords" "EnableBrightnessControl=1;"

  to the Device section. In some case (eg. GeForce GT 650M Mac Edition) it may cause screen flickering during boot time (just after grub screen), and system will not boot. In this case you should use instead add the following: setpci -v -H1 -s 00:01.00 BRIDGE_CONTROL=0

  to the file: /etc/rc.local

• You can check whether or not the kernel module for the NVIDIA driver has been loaded, in addition to what version is currently loaded, by running /sbin/modinfo -F version nvidia-current

• Additional troubleshooting information is available.

Where and how to ask the community for help

ToDo: explain how to properly explain the problem and what background information is needed.

• Debian Nvidia sub-forum

• Nvidia Linux sub-forum

Uninstallation

If you run into issues with the drivers, switch to a different card, or simply want to use the open-source Nouveau drivers instead, uninstallation is made easy with recent versions of the drivers.

Also note that if issues with the driver prevent you from accessing a desktop, you can access a full-screen TTY with Ctrl-Alt-F3 (or almost any of the "F" keys).

You can remove all packages on your system with nvidia and cuda in the name together with their configs and automatic dependencies by running the following command: # apt-get --autoremove purge '*nvidia*' '*nvidia*:i386' '*cuda*' '*cuda*:i386'

Afterwards reboot the system: systemctl reboot

This should leave you with a functioning system in almost all cases. If it seems to still be having issues, you may also try running: # apt install --reinstall xserver-xorg-core xserver-xorg-video-nouveau

Some NVIDIA cards will also need a firmware with nouveau, you might also need to reinstall the firmware with: # apt install --reinstall firmware-nvidia-graphics # update-initramfs -u -k all # systemctl reboot

Or: # X -configure

See Also

• Libre Source (Open Source) alternative to Nvidia Graphics Drivers

  • Mesa

• /Configuration

• /Troubleshooting

• NVIDIA Optimus

• Xorg

• HardwareVideoAcceleration

• ExternalGpu

CategoryProprietarySoftware CategoryHardware CategoryVideo