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

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

Those who prefer open source drivers, for security, privacy, or ideological reasons, may want to avoid these drivers and use the built-in open-source nouveau driver (community developed), although the latter is unfortunately still much less functional and performant than Nvidia's proprietary drivers.

As a consequence of the closed-source nature of the drivers, you should expect planned obsolescence problems, compatibility problems, performance problems and general instability problems in certain configurations. If you don't have knowledge or patience 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 in most cases 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 prefixed with sudo).

As this page has several levels of nested subsections and uses tables, it is recommended to switch to modern theme in your userprefs 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! :)

Want to share a link to some specific section of this page? Chapter names tend to change sometimes, but an effort is made to keep anchors marked with "🔗" character stable.

Contents

  1. GPU identification
  2. Current driver types
    1. Development model and licensing (flavor)
    2. Packaging methods
  3. Community driver recommendations for Trixie & Bookworm (D-13 & D-12)
  4. Installation prerequisites (ALL driver types)
    1. apt components
    2. Kernel headers
    3. SecureBoot
    4. dracut
    5. Backports (optional)
    6. 32bit Intel apps support (optional)
  5. Debian drivers
    1. Debian Unstable "Sid"
    2. Debian 13 "Trixie"
    3. Debian 12 "Bookworm"
    4. Debian 11 "Bullseye"
  6. Nvidia-packaged data-center drivers
    1. CUDA toolkit
    2. Isolated environments
    3. Simplified NV DC driver installation instructions on D-12 & D-13
  7. Tesla Drivers
    1. Kepler GPUs on Trixie & Bookworm (D-13 & D-12)
  8. Suspend and Hibernate configuration
    1. Verifying S0ix support
    2. Debian drivers config
    3. NV DC drivers config
  9. Wayland configuration
  10. X11 configuration
    1. Single GPU
    2. Multiple GPUs
    3. Displays connected to other GPUs
    4. Other scenarios and resources
  11. Optional addons
    1. CUDA toolkit
    2. 32bit Intel libs
    3. Wine DX driver extension
    4. VAAPI driver
    5. OptiX
  12. Redirecting Nvidia GPUs to QEMU+libvirt VMs
    1. Drivers pre-535 on guest VMs
  13. Troubleshooting
    1. Installation problems
    2. Operational problems
    3. Where and how to ask the community for help
  14. Uninstallation
  15. See Also

GPU identification

🔗

You can use lspci to check if you have an Nvidia GPU: 

$ 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)

Current driver types

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 driver version is available in two flavors:

Packaging methods

🔗

There are three major ways that Nvidia drivers are packaged these days:

All 3 types of packaging usually allow to install either open or proprietary flavor for newer versions.

Historically, there were also Debian-packaged data-center drivers, referred to as "Tesla drivers".

When switching between driver packaging methods, it is critical to first purge the old driver before installing the new one.

Failure to do so will result in a mix that almost certainly won't work.

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. It also may be useful to ask the online community for assistance in case of ad-hoc issues.

Community driver recommendations for Trixie & Bookworm (D-13 & D-12)

🔗

The below recommendations are based on user feedback on the Nvidia and Debian forums. They are mostly focused on maximizing supported features and functionality and may differ from so called "official" recommendations.

Don't just blindly apply the instructions in the linked sections!

You should still read the surrounding context and related disclaimers: the fact that something works well even for a majority of cases, does not imply that it is the best solution for your specific scenario.

GPU arch

recommended driver

older than Kepler

built-in Nouveau

Kepler

security-sensitive context: built-in Nouveau
gaming in a properly isolated, trusted environment: Tesla driver v470

Maxwell, Pascal, Volta

NV DC driver v580, proprietary flavor

Turing, Ampere
Ada/Hopper, Blackwell

NV DC driver v595 or the most recent (slight perf variations between these), open flavor

Note for external posts: anchors named directly after Nvidia architectures (for example as in the first column of the table above), will be updated to the most recommended driver for a given architecture as old drivers get obsoleted or new are added. If you instead need a stable link to some specific driver type installation instructions, scroll/navigate to the desired section and use its 🔗 anchor.

Installation prerequisites (ALL driver types)

🔗

apt components

🔗

All components (main, non-free-firmware, non-free and contrib) must be enabled at least for the base suite (like bookworm or trxie or fortky etc depending on your Debian version) and for the -security suite 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 usually also for the -updates: 

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

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

If you have any corresponding deb-src entries configured (for source packages), it is highly recommended to add the components to them as well.

Component non-free-firmware was first introduced in Bookworm, so in case of Bullseye or ealier releases, you may remove it (keeping it won't break anything, but will cause certain apt operations to generate warnings).

Afterwards run 

# apt update

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

You can check 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: these are meta-packages that always depend on the most recent version of the official headers package for a given arch, so whenever a new official kernel package is released, its headers will also be installed automatically during a system upgrade.

If you use some special features kernel like -rt or -cloud (otherwise you can skip the rest of this point), you need to explicitly point the corresponding feature-set headers for your architecture instead of the generic ones mentioned above, for example: 

# apt install linux-headers-rt-amd64

SecureBoot

🔗

If you have SecureBoot enabled (otherwise you can skip this point), you need to enroll your machine owner's key (MOK) to sign & verify the Nvidia modules. Detailed instructions are available here.

dracut

If your system uses dracut (otherwise you can skip this point), you must tell it to include the Nvidia modprobe config files. Create a file somewhere in /etc/dracut.conf.d/ folder, for example /etc/dracut.conf.d/10-nvidia.conf, with the following contents: 

install_items+=" /etc/modprobe.d/nvidia* "

Note: do not omit the spaces between the quotes and the inner string.

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 a Backports suite, then in case of Debian drivers and Tesla drivers, you need to install a driver from the Backports as well (and vice-versa). Also as a side note, if you use a kernel from a Backports suite, it is often necessary to use firmware packages from the Backports as well.

If you want to use a driver from a Backports suite, make sure your system is prepared according to the below steps:

  1. All 4 components (main, contrib, non-free and non-free-firmware) must be enabled for the -backports suite corresponding to your Debian release, for example for Trixie, make sure you have an entry similar to the below somewhere in /etc/apt/sources.list.d/ folder, for example in /etc/apt/sources.list.d/backports.list file: 

    deb http://deb.debian.org/debian/ trixie-backports main contrib non-free non-free-firmware

    • For other Debian releases, replace trixie-backports appropriately with bookworm-backports or bullseye-backports etc.

    • If you have a deb-src entry configured for other suites, it is recommended to add it for the Backports as well.

    • Note, that while it is not recommended, it may happen that the -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 into /etc/apt/sources.list.d/ folder as described here.

  2. To ensure that all kernel and firmware related packages come from the Backports suite, pin them with priority 500 somewhere in /etc/apt/preferences.d/ folder, for example in /etc/apt/preferences.d/kernel-firmware-backports.preffile: 

    Package: src:linux src:linux-signed-amd64 src:linux-base firmware-* *-microcode
Pin: release n=trixie-backports
Pin-Priority: 500

    • In case of an ARM CPU, change linux-signed-amd64 to linux-signed-arm64.

    • For other Debian releases, replace trixie-backports appropriately with bookworm-backports or bullseye-backports etc.

    • You can check the official reference regarding package priorities.

  3. Update apt's DB and upgrade linux-base package first as other kernel packages pre-depend on it: 

    # apt update
# apt install -t trixie-backports linux-base

    For other Debian releases, replace trixie-backports appropriately...

  4. Upgrade the rest of your kernel and firmware packages to the versions from the Backports: 

    # apt dist-upgrade

You can also check the official Backports repo instructions page (note: it uses the "modernized" sources format as opposed to the "traditional" one-line used above: both ways work fine).

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 in: 

# dpkg --add-architecture i386
# apt update

Debian drivers

🔗

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

Before installing any of the below drivers, MAKE SURE that you've completed mandatory steps described in the prerequisites section.

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)

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

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

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

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.

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  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)

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  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).

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  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 '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. If you intend to use suspend or hibernate, configure the related options accordingly.

  3. If you intend to use the NV GPU as a GUI display device, check Wayland or X11 section respectively.

  4. In most cases a reboot 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.

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  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

      As of kernel 6.12.100, the open flavor of this driver (550.163.01-2) no longer compiles (1143204).

      Consider using either the proprietary flavor described above or other packaging methods until this is fixed.

    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.

As of kernels 6.19.x recently released to trixie-backports, this driver (550.163.01-4~bpo13+1) no longer compiles.

If you need a kernel v6.19+, consider other packaging methods until this is fixed.

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  1. Make sure your system is prepared as described in 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 '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. If you intend to use suspend or hibernate, configure the related options accordingly.

  3. If you intend to use the NV GPU as a GUI display device, check Wayland or X11 section respectively.

  4. In most cases a reboot 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.

This version is not maintained since June 2026 and may contain security issues.

It should be used only in properly isolated, trusted environments.

  1. Choose a flavor to install:

    • To install the proprietary flavor, package nvidia-driver should be installed: 

      # apt install nvidia-driver

    • 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

    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 '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. If you intend to use suspend or hibernate, configure the related options accordingly.

  4. If you intend to use the NV GPU as a GUI display device, check Wayland or X11 section respectively.

  5. In most cases a reboot 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).

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments.

  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 '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. Reboot your system to load the new driver.

Nvidia-packaged data-center drivers

🔗

These drivers (often referred to as "NV DC drivers") are intended mostly for compute workloads, but they do contain 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

released CUDA
toolkit versions

10

no

455 - 555

yes / no

Kepler to Ampere with v470 (legacy 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

up to v610 / from v560

Maxwell to Blackwell with v580 (LTS until June 2028);
Turing (but not Volta), Ampere, Ada/Hopper, Blackwell with v590+

12, 13

13

yes

590 - onwards

up to v610 / yes

Turing (but not Volta), Ampere, Ada/Hopper, Blackwell

13

Refer to the official guide regarding installation and usage instructions (simplified version for inexperienced users is here). Some related notes:

General notes:

CUDA toolkit

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

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)

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

Simplified NV DC driver installation instructions on D-12 & D-13

🔗

This section is mostly intended for inexperienced users to make the installation as easy as possible (except the Maxwell/Pascal on D-13 case, which is royally messed-up for everyone). It does not cover several supported customizations (like flavor choosing, compute-only or desktop-only installations etc) and always installs the full driver. For full instructions, refer to the official docs linked above.

Jump to the subsection appropriate for your system:

Turing or newer GPUs on Trixie & Bookworm (D-13 & D-12)

🔗

This section covers Turing (GTX-16xx, RTX-20xx), Ampere (RTX-30xx), Ada/Hopper (RTX-40xx / Hx00) and Blackwell (RTX-50xx, Bx00) GPUs supported by the current mainline drivers. See the full list of supported devices.

  1. MAKE SURE that you've completed mandatory steps described in the prerequisites section.

  2. Export distro env var according to your Debian version:

    • D-12 "Bookworm": 

      $ export distro="debian12"

    • D-13 "Trixie": 

      $ export distro="debian13"

  3. Download the package with Nvidia apt sources config appropriate for your CPU arch:

    • Intel and AMD CPUs: 

      $ wget "https://developer.download.nvidia.com/compute/cuda/repos/${distro}/x86_64/cuda-keyring_1.1-1_all.deb"

    • ARM CPUs: 

      $ wget "https://developer.download.nvidia.com/compute/cuda/repos/${distro}/sbsa/cuda-keyring_1.1-1_all.deb"

  4. Install the downloaded package, update apt's DB and upgrade the system as the Nvidia repo provides newer versions of some system utilities (most notably DKMS) : 

    # dpkg -i cuda-keyring_1.1-1_all.deb
# apt update
# apt dist-upgrade

  5. Optionally, if you want some specific version of the driver instead of the latest, install nvidia-driver-pinning-${VERSION} package and update apt DB, for example for v595: 

    # apt install nvidia-driver-pinning-595
# apt update

    See the version designations here.

  6. Install nvidia-open meta-package: 

    # apt install nvidia-open

    DKMS will build the open modules for your system.

  7. Proceed to post-installation steps.

Maxwell, Pascal and Volta GPUs on Bookworm (D-12)

🔗

This section covers GTX-9xx and GTX-10xx desktop GPUs and data-center GPUs such as V100 family on Debian-12. Nvidia dropped support for these architectures in their drivers after version 580, but 580 series is an LTS that will be receiving critical updates until June 2028. See the full list of devices it supports.

The installation procedure is very similar as for newer GPUs above, with the following changes:

Everything else is identical.

Maxwell, Pascal and Volta GPUs on Trixie (D-13)

🔗

580 LTS series of the driver required for Maxwell/Pascal/Volta support (see the details above), is not available in the D-13 repo, but several users reported, that drivers from the Debian-12 repo generally worked well with Debian-13 as well. This section covers all the work-arounds needed for such installation.

Note: so far this method has been tested only on amd64 CPU arch (Intel/AMD), hence that's what the below instructions assume.

Using drivers originally intended for a different release is at least a bit of a dirty hack and borderline "FrankenDebian".

Proceed at your own risk.

  1. MAKE SURE that you've completed mandatory steps described in the prerequisites section.

  2. Since 2026-02-01, Debian-13 rejects signatures using SHA1 used in the NV D-12 repo. Additionally, D-13 migrated signature verification tool from gpgv to sqv that does not accept additional options from apt sources. To workaround it all, you need to:

    1. Revert back to using gpgv by adding the below config option somewhere in /etc/apt/apt.conf.d/ folder, for example in /etc/apt/apt.conf.d/10gpgv file: 

      APT::Key::GPGVCommand "/usr/bin/gpgv";

    2. Configure apt sources with relaxed verification policy: add the below Nvidia D-12 repo somewhere in /etc/apt/sources.list.d/ folder, for example in /etc/apt/sources.list.d/nvidia-d12.list file: 

      deb [signed-by=/etc/apt/keyrings/nvidia-d12-archive.key allow-insecure=yes] http://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/ /

  3. Download and extract the original Nvidia D-12 repo definition also containing the key: 

    $ wget -O /tmp/nv-d12-repo-config.deb https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb
$ dpkg -x /tmp/nv-d12-repo-config.deb /tmp/nv-d12-repo-config

  4. Copy the Nvidia key to the location pointed in the repo definition from the 2nd point, update apt's DB and upgrade the system as the Nvidia repo provides newer versions of some system utilities (most notably DKMS) : 

    # cp /tmp/nv-d12-repo-config/usr/share/keyrings/cuda-archive-keyring.gpg  /etc/apt/keyrings/nvidia-d12-archive.key
# apt update
# apt dist-upgrade

  5. Install nvidia-driver-pinning-580 package to stay on v580 series of the driver and update apt DB again: 

    # apt install nvidia-driver-pinning-580
# apt update

  6. Install cuda-drivers meta-package: 

    # apt install cuda-drivers

    DKMS will build the proprietary modules for your system.

  7. Proceed to post-installation steps.

If you also install CUDA toolkit to develop/build CUDA apps, depending on the toolkit version, you may need to apply a few tiny patches to one of the header files as described in this thread and this thread. Versions >= 13.2 should not require patching anymore.

Post-installation steps for NV DC drivers

🔗

  1. Optionally verify the result of the DKMS module compilation: 

    # dkms status '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. If you intend to use suspend or hibernate, configure the related options accordingly.

  3. If you have multiple GPUs in your machine and intend to use X11, then proceed to X11 section (Wayland should just work).

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

Tesla Drivers

Tesla drivers are Debian-packaged data-center drivers (same branch as Nvidia-packaged data-center drivers). As of 2026, all available versions in any Debian realease have reached their EOL upstream and thus should not be used for any DC deployments. Use the mentioned NV DC drivers instead.

The name comes from the Nvidia's first DC-dedicated architecture. It is sometimes still used across NV's documentation and URLs.

Kepler GPUs on Trixie & Bookworm (D-13 & D-12)

🔗

Version 470.256.02 is the last that supports Kepler GPUs. Its Tesla variant is available in bookworm, bookworm-backports and unstable suites and can be easily installed also on Trixie when using 6.12 kernel from the main trixie suite. Patches for kernels 7.x are available also, so with some gymnastics, it is possible to install it when using kernels from trixie-backports as well.

This version is no longer maintained and contains several security issues.

It should be used only in properly isolated, trusted environments: on virtual machines or spare computers that don't have network access to any other systems and that ideally have their drives wiped clean on a regular basis.

First, MAKE SURE that you've completed mandatory steps described in the prerequisites section, then proceed to the subsection appropriate for your system:

Bookworm, kernels 6.1.x

  1. Install nvidia-tesla-470-driver package: 

    # apt install nvidia-tesla-470-driver

    DKMS will build the modules for your system.

  2. Proceed to post-installation steps.

Bookworm, kernels 6.12.x from Backports

  1. Make sure your system is prepared as described in Backports section.

  2. Install nvidia-tesla-470-driver package from bookworm-backports: 

    # apt install -t bookworm-backports nvidia-tesla-470-driver

    DKMS will build the modules for your system.

  3. Proceed to post-installation steps.

Trixie, kernels 6.12.x

The procedure consists of configuring apt sources in a way that will not affect unrelated parts of the system and then installing the driver.

Note: using bookworm-backports is usually preferred over unstable as the latter tends to pull some additional dependencies outside of Nvidia driver packages (under certain circumstances apt may even replace the whole glibc when installing this driver from unstable). Moreover, while the version from unstable seems newer, it is based on the same proprietary binaries anyway and currently does not compile on 7.3.x kernels either. If you however have a strong preference for unstable, then replace all occurrences of bookworm-backports / n=bookworm-backports with unstable / a=unstable in the below configs and it should generally work fine: just pay attention during any subsequent apt operations if you are not upgrading half of your system to Sid.

Using drivers originally intended for a different release is at least a bit of a dirty hack and borderline "FrankenDebian".

Proceed at your own risk.

  1. Add bookworm-backports sources somewhere in /etc/apt/sources.list.d/ folder, for example in /etc/apt/sources.list.d/bookworm-backports.list file: 

    deb http://deb.debian.org/debian/ bookworm-backports non-free-firmware non-free contrib main
deb-src http://deb.debian.org/debian/ bookworm-backports non-free-firmware non-free contrib main

  2. To ensure that related packages always come from bookworm-backports suite, including during system upgrades, while unrelated packages don't conflict with trixie-backports (in case you have it enabled), add a file with the below contents somewhere in /etc/apt/preferences.d/ folder, for example in /etc/apt/preferences.d/nvidia-kepler.pref file: 

    Package: *
Pin: release n=bookworm-backports
Pin-Priority: 90

Package: *nvidia-tesla-470*
Pin: release n=bookworm-backports
Pin-Priority: 510

  3. Update apt DB: 

    # apt update

  4. If you intend to install 32-bit libs (nvidia-tesla-470-driver-libs:i386), it is recommended to first install libglx0:i386 and libegl1:i386 from trixie suite before the driver: 

    # apt install libglx0:i386 libegl1:i386

    This should make the next step install nvidia-tesla-470-driver-libs:i386 automatically (depending on your other configured sources, apt may sometimes fail to calculate dependencies coming from different suites).

  5. Install nvidia-tesla-470-driver package: 

    # apt install nvidia-tesla-470-driver

    DKMS will build the modules for your system.

  6. Proceed to post-installation steps.

Trixie, kernels 7.x

The procedure consists of configuring patch overriding for the DKMS module sources and then proceeding the same way as in the case of kernels 6.12.x.

Many ppl would call this "a full-blown FrankenDebian"...

...but that's a sad consequence of planned obsolescence by Nvidia :(

Applying kernel patches from 3rd party community repos DRAMATICALLY increases the risk of supply-chain attacks!!

If you don't have a knowledge to verify the patches before following the below procedure, you should treat any machine using the patched modules as TOTALLY PWND until a complete OS reinstallation.

When loading the driver on kernels 7.x, a warning will be generated in system logs: "Unpatched return thunk in use. This should not happen!". This seems to be mostly harmless, see details in this Nvidia forums thread.

Recently released to unstable version 470.256.02-10 does compile on kernels up to 7.2.x, so if you don't plan to use kernels 7.3.x or newer in a near future, you can proceed to the instructions for kernels 6.12.x right away and use unstable instead of bookworm-backports as explained in the initial note there.

  1. DKMS version 3.4.x is required for support of patch overriding: it's not yet available even in Sid, so download and install it from the NV DC repo, currently v3.4.3: 

    $ wget -O /tmp/dkms.deb https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/dkms_3.4.3-1_all.deb
# apt install /tmp/dkms.deb

    If you prefer, you can instead add the NV DC repo to apt sources as described at the beginning of the instructions for NV DC drivers and install just dkms from there (up to and including point 4). The advantage is that this way you will receive any future upgrades to DKMS automatically.

  2. Clone the patches repo and copy them into /etc/dkms/nvidia-tesla-470/patches/ folder: 

    $ git clone --depth=1 https://github.com/joanbm/nvidia-470xx-linux-mainline.git /tmp/nvidia-470xx-linux-mainline
# mkdir -p /etc/dkms/nvidia-tesla-470/patches/
# cp /tmp/nvidia-470xx-linux-mainline/patches/*.patch /etc/dkms/nvidia-tesla-470/patches/

  3. Create a patch override config replacing all 28 patches from nvidia-tesla-470-kernel-dkms=470.256.02-5~bpo12+1 package with the ones copied above: 

    $ grep '^apply_patch ' /tmp/nvidia-470xx-linux-mainline/extract_and_patch |sed -e 's@apply_patch @@' >/tmp/nvidia-tesla-470-patches.txt
$ i=0; while read filename; do echo "PATCH[${i}]=${filename}"; i=$(( i + 1 )); done </tmp/nvidia-tesla-470-patches.txt >/tmp/nvidia-tesla-470.conf
$ for (( ; i < 28; i++)); do echo "PATCH[${i}]="; done >>/tmp/nvidia-tesla-470.conf
# cp /tmp/nvidia-tesla-470.conf /etc/dkms/

    As of commit b68e153, the resulting /etc/dkms/nvidia-tesla-470.conf file should look like the below: 

    PATCH[0]=0001-Fix-conftest-to-ignore-implicit-function-declaration.patch
PATCH[1]=0002-Fix-conftest-to-use-a-short-wchar_t.patch
PATCH[2]=0003-Fix-conftest-to-use-nv_drm_gem_vmap-which-has-the-se.patch
PATCH[3]=kernel-6.10.patch
PATCH[4]=kernel-6.12.patch
PATCH[5]=nvidia-470xx-fix-gcc-15.patch
PATCH[6]=nvidia-470xx-fix-linux-6.13.patch
PATCH[7]=nvidia-470xx-fix-linux-6.14.patch
PATCH[8]=nvidia-470xx-fix-linux-6.15.patch
PATCH[9]=nvidia-470xx-fix-linux-6.17.patch
PATCH[10]=nvidia-470xx-fix-linux-6.19-part1.patch
PATCH[11]=nvidia-470xx-fix-linux-6.19-part2.patch
PATCH[12]=nvidia-470xx-fix-linux-7.0.patch
PATCH[13]=nvidia-470xx-fix-linux-7.2-part1.patch
PATCH[14]=nvidia-470xx-fix-linux-7.2-part2.patch
PATCH[15]=nvidia-470xx-fix-linux-7.2-part3.patch
PATCH[16]=nvidia-470xx-fix-linux-7.3.patch
PATCH[17]=disable-objtool-override.patch
PATCH[18]=enable-drm-modeset-by-default.patch
PATCH[19]=
PATCH[20]=
PATCH[21]=
PATCH[22]=
PATCH[23]=
PATCH[24]=
PATCH[25]=
PATCH[26]=
PATCH[27]=

  4. Proceed to the instructions for kernels 6.12.x.

Post-installation steps for Kepler GPUs

  1. Fix the supported Vulkan version from 1.3.xxx (wrongly provided by driver v535/550) to the actual 1.2.175 in /usr/share/vulkan/implicit_layer.d/nvidia_layers.json and /usr/share/vulkan/implicit_layer.d/nvidia_layers.json files: 

    $ sed -e 's@"api_version" : "1.3...."@"api_version" : "1.2.175"@' /usr/share/vulkan/icd.d/nvidia_icd.json >/tmp/nvidia_icd.json
# cp /tmp/nvidia_icd.json /usr/share/vulkan/icd.d/nvidia_icd.json
$ sed -e 's@"api_version" : "1.3...."@"api_version" : "1.2.175"@' /usr/share/vulkan/implicit_layer.d/nvidia_layers.json >/tmp/nvidia_layers.json
# cp /tmp/nvidia_layers.json /usr/share/vulkan/implicit_layer.d/nvidia_layers.json

  2. This driver does not support nvidia-persistenced available in Bookworm/Trixie repos (v535/v550), so disable it: 

    # systemctl disable nvidia-persistenced.service

    Legacy persistence mode still works regardless and if you need it, it may be enabled with the below command after the driver is loaded: 

    # nvidia-smi -pm 1

  3. If you intend to use suspend or hibernate, configure the related options accordingly.

  4. If you intend to use the NV GPU as a GUI display device, check X11 section (Wayland is very unlikely to work on Kepler GPUs).

  5. In most cases a reboot of the system is recommended to fully load the new driver.

  • If you intend to use DXVK, note that the current versions will not work on Kepler GPUs as they require Vulkan-1.3 support at least, so you will need to stick to 1.10.x series at most (latest release as of Sep 2026: 1.10.3) and corresponding DXVK-NVAPI versions (0.4, 0.5.x or 0.6). Also some recent version of Wine Staging may be needed for some programs.

  • When this driver is loaded, certain versions of Wine will fail to start, if the display is not on the Nvidia GPU (the process will just hang until killed).

Suspend and Hibernate configuration

🔗

Suspend and hibernate have been quite problematic with NV GPUs, this to some extent may have been caused by the configuration defaults of power management options that do not work well in many scenarios.

Verifying S0ix support

  1. Install acpica-tools: 

    # apt install acpica-tools

  2. In some temporary folder (like /tmp/) run 

    # acpidump -b

    This will produce a bunch of *.dat files.

  3. In the same folder run 

    $ iasl -d *.dat

    This will produce a (mostly) human-readable file named facp.dsl among others.

  4. Check the value of of Low Power S0 Idle inside that file: 

    $ grep "Low Power S0 Idle" facp.dsl

    1 means that S0ix is supported.

See this article for details.

Debian drivers config

Both Trixie and Bookworm packages provide /etc/modprobe.d/nvidia-options.conf that contains a template of options for proprietary flavor and older versions of open one (including versions currently packaged by Debian), but all the settings are commented out. Therefore, unless you have an Optimus laptop:

  1. Uncomment the entry enabling NVreg_PreserveVideoMemoryAllocations.

  2. If your system supports S0ix, then uncomment also the entry for NVreg_EnableS0ixPowerManagement

  3. Depending on your Debian release:

    • In case of Trixie, additionally append 

      options nvidia NVreg_TemporaryFilePath=/var/tmp
      at the end of the file.

    • In case of Bookworm, /proc/driver/nvidia/suspend related Systemd services are usually disabled by default, so enable them with the below commands: 

      # systemctl enable nvidia-suspend.service nvidia-hibernate.service nvidia-resume.service

NV DC drivers config

Versions up to 590

The packages for both Trixie and Bookworm provide /etc/modprobe.d/nvidia.conf that should work fine on most hardware with both flavors, so you usually do not need to do anything. If however your machine does not support S0ix, you need to remove NVreg_EnableS0ixPowerManagement line from the config file.

Versions 595 and 610

The packages for both Trixie and Bookworm provide /etc/modprobe.d/nvidia.conf that contains configuration for proprietary. Therefore if you use:

In both cases, if your machine does not support S0ix, you need to remove NVreg_EnableS0ixPowerManagement line from the config file.

Versions from 615 onwards

As proprietary flavor was dropped, packages now provide /etc/modprobe.d/nvidia.conf that should work on most supported configurations: NVreg_UseKernelSuspendNotifiers, NVreg_PreserveVideoMemoryAllocations and NVreg_EnableS0ixPowerManagement are all enabled. If however your machine does not support S0ix, you need to remove NVreg_EnableS0ixPowerManagement line from the config file.

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).

  1. Make sure that you have configured suspend+hibernate related options accordingly to your driver type: in case of proprietary flavor, option NVreg_PreserveVideoMemoryAllocations is mandatory for Wayland.

  2. Options modeset and fbdev of nvidia_drm module must be enabled. You can verify it by the contents of /sys/module/nvidia_drm/parameters/modeset and /sys/module/nvidia_drm/parameters/fbdev virtual files: they both should contain 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-drm modeset=1
options nvidia-drm fbdev=1

X11 configuration

🔗

X11 is a "traditional" base of Linux GUI system. It is used for example by such desktop-environments as MATE of XFCE.

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 occurrences 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, it is also possible to use displays connected to those other than the Nvidia one (like for example your laptop's internal display connected to the iGPU). First, modeset and fbdev params of nvidia_drm module need to be enabled, similarly like in the case of Wayland. Next, you usually need to configure such setup explicitly (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 full 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

Optional addons

CUDA toolkit

This section refers to Debian-packaged CUDA toolkit. If you use Nvidia-packaged DC drivers, you also need to use the Nvidia-packaged toolkit.

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 toolkit
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

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

Wine DX driver extension

If you use Wine with Vulkan DX drivers (DXVK, VKD3D-proton), then it is hightly recommended to also install DXVK-NVAPI. This allows several programs to properly detect your NV GPU.

VAAPI driver

Nvidia does not provide a VA-API driver needed for hardware video acceleration in browsers like Firefox, but a 3rd party open-source driver built on top of NVAPI / NVDEC exists: nvidia-vaapi-driver. Refer to the project's README file for configuration details.

OptiX

Debian-packaged driver meta-packages do not pull OptiX Ray Tracing runtime by default, but it can be installed separately: 

# apt install libnvoptix1

In case of Tesla drivers, the corresponding package is named libnvidia-tesla-${VERSION}-nvoptix1, for example for v470: 

# apt install libnvidia-tesla-470-nvoptix1

Nvidia-packaged drivers pull OptiX in by default.

Redirecting Nvidia GPUs to QEMU+libvirt VMs

🔗

When redirecting PCIe devices to a VM, QEMU needs to allocate right away and keep the whole amount of the VM's configured RAM.

  1. Unless it's a headless server, make sure the display is handled by another GPU and that no processes run on the GPU to be redirected (as reported by nvidia-smi).

  2. Either dynamically unbind or statically blacklist the GPU from nvidia and nouveau modules on the supervisor host machine.

  3. If the Nvidia card provides an audio controller, it must be also unbound or blacklisted from snd_hda_intel module.

  4. Both PCIe devices provided by the card (if both are present that is) must be redirected to the target guest VM in its definition via vfio_pci module, for example:

    • GPU: 

      <hostdev mode="subsystem" type="pci" managed="yes">
  <source>
    <address domain="0x0000" bus="0x03" slot="0x00" function="0x0"/>
  </source>
  <address type="pci" domain="0x0000" bus="0x07" slot="0x00" function="0x0" multifunction="on"/>
</hostdev>

    • audio: 

      <hostdev mode="subsystem" type="pci" managed="yes">
  <source>
    <address domain="0x0000" bus="0x03" slot="0x00" function="0x1"/>
  </source>
  <address type="pci" domain="0x0000" bus="0x07" slot="0x00" function="0x1"/>
</hostdev>

    If you use virt-manager GUI:

    1. Inside the VM window switch to details (the light bulb button in the top bar)

    2. Click Add Hardware button in the bottom-left corner.

    3. Select PCI Host Device in the left menu of the dialog window.

    4. Choose the GPU first.
    5. Repeat the process for the audio controller (if present).

    6. By default the audio controller will end up as a separate PCIe device with a different bus ID than the GPU. While not strictly necessary, it is recommended to edit its XML (select it in the left list of the VM devices, then switch to XML tab in the top bar of the subwindow) to be function 0x1 of the same bus and slot as the GPU: see the above XMLs (this should automatically add multifunction="on" to the GPU's XML).

  5. Optionally the PCIe devices may be statically bound to vfio_pci module on the supervisor host using ids param: this will prevent them from binding to nouveau and snd_hda_intel modules and will also slightly speed up the VM start. It is still recommended to blacklist the GPU from nvidia module on the host if possible (and if it's installed at all) as this one sometimes precedes vfio_pci.

  6. Inside the guest VM, all that is necessary is to install the Nvidia driver.

Drivers pre-535 on guest VMs

Older versions of Nvidia drivers blatantly refuse to load on VMs, resulting in RmInitAdapter failed (0x22:0x56:667) message in the logs. Fortunately this no longer the case since v535, but if you are forced to use some ancient version (for example for Kepler GPUs), then you must configure the VM to trick the driver to think it's not a VM:

For example: 

<domain type="kvm">

  <!--
    other stuff here...
  -->

  <features>
    <acpi/>
    <apic/>
    <kvm>
      <hidden state="on"/>
    </kvm>
    <vmport state="off"/>
  </features>

  <cpu mode="host-passthrough" check="none" migratable="on">
    <feature policy="disable" name="hypervisor"/>
  </cpu>

  <!--
    other stuff here...
  -->

</domain>

See this Proxmox article for details.

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:

Kernel modules build skipped

🔗

Symptoms:

Possible reasons and resolutions:

This is due to missing kernel headers appropriate for one of your installed kernels. Make sure that you have appropriate headers packages installed as described in Kernel headers section. Also, the above output provides a hint, but only for the exact kernel version you are currently running, so if you blindly follow and install only this exact package, it may stop working after booting to another kernel version. Generalize the hint by removing the ABI 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:

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.

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.

Operational problems

Black screen right after boot menu

ToDo: explain:

  1. how 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

GPU has fallen off the bus

🔗

Symptoms:

Everything initially works, but suddenly applications crash or the system freezes completely. In the logs there are messages similar to the below: (PCI bus ID will likely differ) 

NVRM: Xid (PCI:0000:01:00): 79, GPU has fallen off the bus.

Possible reasons and resolutions:

  1. In the words of an Nvidia eng, "GPU falling off the bus is often a bios, power supply or thermal issue", therefore:

    • Make sure you are using the latest possible driver version for your GPU as it may be bringing GSP firmware fixes.
    • Check if there's a firmware update available for your mobo from its manufacturer: this often resolves the issue.
    • Make sure your PSU is able to deliver sufficient amount of juice, don't use off-brand PSUs or models known to cause issues.
    • Watch your thermals and if they exceed 90 degrees, check the cooling system (fans, thermal paste).

  2. High-end Blackwell models (5080, 5090, Pro 5000, Pro 6000) are notorious (1, 2) for falling off buses without any reason. It is speculated that they are actually overheating, but the firmware hides this fact from users. Some users reported that limiting maximum clock speed or locking it permanently to a fixed value with nvidia-smi -lgc mitigates the issue, but it does not help in every case. For example: 

    nvidia-smi -lgc 180,2400

    See man nvidia-smi for details.

  3. In case of external GPUs, falling off the bus may be an indicator of an unstable connection:
  4. Physical damage to PCIe connectors.

Other operational problems

ToDo: explain:

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

Miscellaneous

ToDo: this subsection may be partially out of date.

Where and how to ask the community for help

🔗

Relevant Debian and Nvidia subforums:

Required info when asking for assistance:

Also recommended is a bug report file created by sudo nvidia-bug-report.sh, note however that this file may contain some personal identifiable info, such as serial numbers, network addresses, usernames etc, so check before posting.

Uninstallation

🔗

  1. The first step depends on the packaging method that was used to install the driver:

    • In case of dot-run installers, you may try --uninstall option, but a complete reinstallation of the OS is more recommended.

  2. If you configured X11 explicitly to use nvidia driver, you must revert it (unless you intend to install another proprietary driver right away).

  3. If you want to use the open-source Nouveau driver after that, then follow the below sub-steps:
    1. Install the firmware needed by Nouveau:

      • On Trixie it is in a dedicated firmware-nvidia-graphics package: 

        # apt install firmware-nvidia-graphics

        If you use a kernel from trixie-backports, then instead install the version from trixie-backports as well: 

        # apt install -t trixie-backports firmware-nvidia-graphics

      • On Bookworm, if you use a kernel from the Backports, the firmware is also in firmware-nvidia-graphics: 

        # apt install -t bookworm-backports firmware-nvidia-graphics

      • In Bookworm's base suite and on Bullseye, the firmware is a part of firmware-misc-nonfree: 

        # apt install firmware-misc-nonfree

    2. On older Debian versions you may also need to reinstall X11 drivers: 

      # apt install --reinstall xserver-xorg-core xserver-xorg-video-nouveau
  4. In most cases a reboot of the system is recommended to fully purge the old driver. In case you intend to install another driver, you can usually defer a reboot to post-installation.

See Also

CategoryProprietarySoftware CategoryHardware CategoryVideo