How to Install CUDA on Debian

CUDA (Compute Unified Device Architecture) enables Debian systems to offload parallel workloads to NVIDIA GPUs for machine learning training, video encoding, scientific simulations, and computational research. The toolkit includes nvcc (the CUDA compiler), Nsight profiling tools, and GPU-accelerated libraries such as cuBLAS, cuFFT, and cuSPARSE that integrate with frameworks like PyTorch and TensorFlow.

This guide covers two installation paths: Debian’s default repositories for stability-focused environments, and NVIDIA’s official CUDA repository for developers who need the latest toolkit versions and GPU features. By the end, you will have a working CUDA development environment with verified driver and compiler installations ready for GPU-accelerated applications.

Choose Your CUDA Installation Method

Debian provides two paths for CUDA Toolkit installation, each with different version availability, update frequency, and stability trade-offs. Understanding these differences helps you select the method that matches your Debian version and project requirements.

Method	Channel	Debian Support	Stability	Best For
Debian Default Repository	Debian Packages	Debian 13, 12, 11 (x86_64)	High stability, conservative updates, thorough distribution testing	Production environments, stability over latest features
NVIDIA CUDA Repository	NVIDIA Repository	Debian 13, 12, 11 (x86_64); Debian 13, 12 (SBSA/ARM64)	Latest CUDA versions, frequent updates, minimal delay from NVIDIA release	Machine learning development, CUDA application development, newest GPU features

For most users, the NVIDIA CUDA Repository is recommended because it provides the latest CUDA toolkit versions and compatible driver updates. In contrast, Debian’s default repository is best for production environments where stability matters more than having the newest features. The NVIDIA repository currently offers CUDA 13.x, while Debian 13’s default repository provides CUDA 12.4, Debian 12 provides CUDA 11.8, and Debian 11 provides CUDA 11.2.

Debian 11 (Bullseye) is in Long Term Support (LTS) status until August 2026. While the instructions in this guide work on Debian 11, consider upgrading to Debian 12 or 13 for access to newer CUDA versions and longer support timelines.

Clean Up Previous NVIDIA Installations

Skip this section if you are installing CUDA on a fresh Debian system for the first time. Only use these cleanup steps if you are upgrading CUDA versions, reinstalling after a failed installation, switching from Nouveau to proprietary drivers, or removing a previous runfile installation.

Remove NVIDIA Packages Installed via APT

If you previously installed NVIDIA drivers or CUDA using APT, remove all related packages before proceeding. The quotes around the package patterns prevent shell glob expansion issues:

sudo apt remove 'cuda*' 'nvidia*' --purge
sudo apt autoremove --purge

The --purge flag removes configuration files along with the packages, ensuring a clean slate. After removal, update your package cache:

sudo apt update

Remove NVIDIA Drivers Installed via Runfile

If you installed NVIDIA drivers using a .run file downloaded from NVIDIA’s website, the standard APT removal process will not work. Instead, use the uninstaller that came with the runfile installation:

sudo /usr/bin/nvidia-uninstall

This script removes the driver components and kernel modules that the runfile installer created. However, if the uninstaller script does not exist, the runfile installation may have been incomplete or already removed.

Remove CUDA Toolkit Installed via Runfile

Similarly, if you installed the CUDA toolkit using a separate runfile, remove it before installing from APT repositories. Replace X.Y with your installed CUDA version number:

sudo /usr/local/cuda-X.Y/bin/cuda-uninstall

Common version paths include /usr/local/cuda-12.4, /usr/local/cuda-11.8, or similar. Check what exists in /usr/local/ if you are unsure which version is installed.

Pre-Installation Steps

Update System Packages

First, update your package index and upgrade existing packages. This ensures kernel headers and dependencies match your current system state, which is important because NVIDIA drivers compile kernel modules during installation:

sudo apt update
sudo apt upgrade

If the upgrade installed a new kernel version, reboot before continuing so that the running kernel matches the installed headers.

Install Required Packages

Install the packages needed for repository configuration and GPG key handling:

sudo apt install curl gpg -y

Specifically, the curl package downloads repository keys, and gpg converts ASCII-armored keys to the binary format that APT requires. These packages may already be installed on desktop systems but are often missing on minimal or server installations.

Enable Contrib and Non-Free Repositories

NVIDIA CUDA packages reside in Debian’s non-free repositories due to proprietary licensing. Before installation, you must enable the contrib and non-free repositories. The configuration method differs between Debian versions.

Debian 13 (Trixie) and Debian 12 (Bookworm) use DEB822 format configuration files. Edit the sources file to add the required components:

sudo sed -i 's/Components: main/Components: main contrib non-free non-free-firmware/' /etc/apt/sources.list.d/debian.sources

Debian 11 (Bullseye) uses the traditional sources.list format. Edit the file to add contrib and non-free to each line:

sudo sed -i 's/main$/main contrib non-free/' /etc/apt/sources.list

Debian 11 does not have a non-free-firmware component. This component was introduced in Debian 12 to separate firmware packages from other non-free software. If you add non-free-firmware on Debian 11, APT will report an error about a missing component.

After modifying the repository configuration, update your APT cache to load packages from the newly enabled components:

sudo apt update

Method 1: Install CUDA from Debian Default Repository

Debian’s default repository provides CUDA packages that have undergone extensive distribution testing, making this method ideal for production environments where predictable behavior matters more than having the absolute latest version. Consequently, this method requires no additional repository configuration beyond enabling non-free.

To begin, install the CUDA Toolkit and NVIDIA drivers from Debian’s repositories:

sudo apt install nvidia-cuda-toolkit nvidia-driver

This command installs the CUDA compiler (nvcc), GPU-accelerated libraries, development headers, and matching NVIDIA drivers. Specifically, the nvidia-cuda-toolkit package includes cuBLAS, cuFFT, cuSPARSE, and other libraries commonly used in CUDA development.

Before installation, verify which version will be installed:

apt-cache policy nvidia-cuda-toolkit

Example output on Debian 13:

nvidia-cuda-toolkit:
  Installed: (none)
  Candidate: 12.4.131~12.4.1-2
  Version table:
     12.4.131~12.4.1-2 500
        500 http://deb.debian.org/debian trixie/non-free amd64 Packages

Debian’s packages place nvcc in /usr/bin and libraries in /usr/lib/x86_64-linux-gnu, so PATH and library variables work by default. You do not need to configure environment variables if you use this installation method.

After installation completes, reboot your system to load the NVIDIA kernel modules and disable the Nouveau open-source driver:

sudo reboot

Once your system restarts, skip ahead to the verification section to confirm your installation works correctly.

Method 2: Install CUDA from NVIDIA Repository

The NVIDIA CUDA repository provides the newest toolkit and driver releases, typically within days of NVIDIA publishing them. This method supports Debian 13 (Trixie), Debian 12 (Bookworm), and Debian 11 (Bullseye). Additionally, both x86_64 and SBSA/ARM64 architectures are supported for Debian 12 and 13, while Debian 11 supports x86_64 only.

Import the NVIDIA GPG Key

First, download and install the NVIDIA GPG signing key. Debian 13 uses a newer key than Debian 11 and 12, so choose the command matching your Debian version.

For Debian 13 Trixie (x86_64):

curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/8793F200.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg

On Debian 13 Trixie (SBSA/ARM64):

curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian13/sbsa/8793F200.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg

For Debian 12 Bookworm (x86_64):

curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/3bf863cc.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg

On Debian 12 Bookworm (SBSA/ARM64):

curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian12/sbsa/3bf863cc.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg

On Debian 11 Bullseye (x86_64):

curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian11/x86_64/3bf863cc.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg

The gpg --dearmor command converts the ASCII-armored key to binary format, which APT requires for signed repository verification.

Add the NVIDIA CUDA Repository

Next, add the NVIDIA CUDA repository using DEB822 format for Debian 12 and 13, or the legacy format for Debian 11. Choose the command matching your Debian version and architecture.

For Debian 13 Trixie (x86_64):

echo "Types: deb
URIs: https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/
Suites: /
Signed-By: /usr/share/keyrings/nvidia-cuda.gpg" | sudo tee /etc/apt/sources.list.d/nvidia-cuda.sources

On Debian 13 Trixie (SBSA/ARM64):

echo "Types: deb
URIs: https://developer.download.nvidia.com/compute/cuda/repos/debian13/sbsa/
Suites: /
Signed-By: /usr/share/keyrings/nvidia-cuda.gpg" | sudo tee /etc/apt/sources.list.d/nvidia-cuda.sources

For Debian 12 Bookworm (x86_64):

echo "Types: deb
URIs: https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/
Suites: /
Signed-By: /usr/share/keyrings/nvidia-cuda.gpg" | sudo tee /etc/apt/sources.list.d/nvidia-cuda.sources

On Debian 12 Bookworm (SBSA/ARM64):

echo "Types: deb
URIs: https://developer.download.nvidia.com/compute/cuda/repos/debian12/sbsa/
Suites: /
Signed-By: /usr/share/keyrings/nvidia-cuda.gpg" | sudo tee /etc/apt/sources.list.d/nvidia-cuda.sources

On Debian 11 Bullseye (x86_64):

echo 'deb [signed-by=/usr/share/keyrings/nvidia-cuda.gpg] https://developer.download.nvidia.com/compute/cuda/repos/debian11/x86_64/ /' | sudo tee /etc/apt/sources.list.d/nvidia-cuda.list

The NVIDIA repository uses a flat structure (Suites: /) rather than traditional Debian suites like stable or bookworm. This is why the DEB822 configuration does not include a Components field.

Update Package Cache

After adding the repository, refresh your package cache to make the NVIDIA packages available:

sudo apt update

Verify Available CUDA Versions

Before installation, check which CUDA versions the NVIDIA repository provides:

apt-cache policy cuda

Expected output showing the NVIDIA repository as the package source:

cuda:
  Installed: (none)
  Candidate: 13.1.0-1
  Version table:
     13.1.0-1 500
        500 https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64  Packages

The version number will vary based on your Debian release and when you run the command. Verify that the NVIDIA repository URL appears in the version table; if only Debian’s default repository appears, the NVIDIA repository was not added correctly.

Install CUDA Toolkit and NVIDIA Drivers

To proceed, install the CUDA toolkit metapackage along with the NVIDIA driver:

sudo apt install cuda nvidia-driver

The cuda metapackage installs the latest CUDA version from the NVIDIA repository, including nvcc, cuBLAS, cuFFT, cuSPARSE, Nsight development tools, and compatible drivers. The nvidia-driver package ensures you receive the driver version tested with your CUDA toolkit.

NVIDIA drivers use DKMS (Dynamic Kernel Module Support) to automatically rebuild kernel modules when you install kernel updates. This maintains driver functionality across kernel upgrades without manual intervention. For comprehensive driver troubleshooting and standalone driver installation options, see the NVIDIA drivers on Debian guide.

If your system has Secure Boot enabled, the NVIDIA driver installation will prompt you to create a Machine Owner Key (MOK) password. You must enroll this key during the next reboot by selecting “Enroll MOK” from the blue MOK management screen. Without MOK enrollment, the NVIDIA kernel modules will not load. Alternatively, you can disable Secure Boot in your BIOS/UEFI settings before installation.

Reboot to Activate the Drivers

After installation completes, reboot your system to load the NVIDIA kernel modules and disable the Nouveau driver:

sudo reboot

Verify Your CUDA Installation

Check NVIDIA Driver Status

After rebooting, verify that the NVIDIA driver loaded correctly and CUDA can access your GPU:

nvidia-smi

This output displays your GPU model, driver version, CUDA version, memory usage, and running processes:

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 560.xx.xx    Driver Version: 560.xx.xx    CUDA Version: 13.x    |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:01:00.0 Off |                  N/A |
|  0%   35C    P8    10W / 250W |      1MiB /  8192MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+

This output confirms the driver loaded successfully and shows the GPU hardware details. Notably, the CUDA version in the header indicates the highest CUDA version this driver supports, not necessarily the version you installed.

Verify the CUDA Compiler

Next, check that the CUDA compiler is accessible:

nvcc --version

Expected output shows the installed CUDA toolkit version:

nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Wed Nov 20 15:25:34 PST 2024
Cuda compilation tools, release 13.1, V13.1.80
Build cuda_13.1.r13.1/compiler.35767370_0

If nvcc is not found, see the Configure CUDA Environment Variables section below.

Configure CUDA Environment Variables

When you install CUDA from the NVIDIA repository, the toolkit installs to /usr/local/cuda rather than system directories. As a result, you need to add CUDA to your PATH and library search path.

Skip this step if you installed from Debian’s default repository. The nvidia-cuda-toolkit package places binaries in /usr/bin and libraries in /usr/lib, which are already in your default paths.

Then, add the CUDA paths to your shell configuration:

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

The PATH addition allows running nvcc and other CUDA tools directly. Meanwhile, the LD_LIBRARY_PATH addition ensures compiled CUDA programs find GPU-accelerated libraries at runtime. Finally, the source command applies these changes to your current terminal session.

Afterward, verify the configuration by checking which nvcc binary your shell finds:

which nvcc

Expected output for NVIDIA repository installations:

/usr/local/cuda/bin/nvcc

Test CUDA with a Sample Program

To confirm everything works, verify your CUDA installation by compiling and running a simple GPU program. This test confirms that nvcc can compile code, the driver can communicate with the GPU, and the runtime libraries are accessible.

Create a Hello World Program

First, create a new file with the .cu extension, which is standard for CUDA source files:

nano helloworld.cu

Next, add the following CUDA program that prints messages from both the CPU and GPU:

#include <stdio.h>
#include <cuda_runtime.h>

__global__ void helloFromGPU(void) {
    printf("Hello World from GPU!\n");
}

int main(void) {
    printf("Hello World from CPU!\n");
    helloFromGPU <<<1, 10>>>();
    cudaDeviceSynchronize();
    return 0;
}

Save the file (Ctrl+O, Enter, Ctrl+X in nano). The __global__ keyword marks helloFromGPU as a GPU kernel function that runs on the graphics card. The <<<1, 10>>> syntax launches the kernel with 1 block of 10 threads, so you will see the GPU message printed 10 times.

Compile and Run the Program

Then, compile the program using the NVIDIA CUDA compiler:

nvcc helloworld.cu -o helloworld

Once compilation succeeds without errors, run the compiled program:

./helloworld

Expected output:

Hello World from CPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!
Hello World from GPU!

The CPU message appears first, followed by 10 GPU messages (one per thread). This output confirms your CUDA installation is working correctly.

Troubleshooting Common Issues

nvidia-smi Not Found or GPU Not Detected

When nvidia-smi returns “command not found” or shows no GPU, check whether the NVIDIA kernel modules loaded:

lsmod | grep nvidia

Expected output when drivers are loaded correctly:

nvidia_drm            114688  0
nvidia_modeset       1306624  1 nvidia_drm
nvidia_uvm           3158016  0
nvidia              62881792  2 nvidia_uvm,nvidia_modeset

If no output appears, the driver modules did not load. Check the kernel log for errors:

sudo dmesg | grep -i nvidia

Common causes include Secure Boot blocking unsigned modules, DKMS failing to compile the module, or kernel version mismatch. Therefore, try rebooting first, as some installations require a reboot for DKMS to finish building modules:

sudo reboot

nvcc Command Not Found

When nvcc --version returns “command not found” after installing from the NVIDIA repository, the CUDA path is not in your environment. First, verify nvcc exists:

ls /usr/local/cuda/bin/nvcc

If the file exists, add the environment variables described in the Configure CUDA Environment Variables section above. Otherwise, if the file does not exist, the CUDA toolkit did not install properly. Reinstall it:

sudo apt install --reinstall cuda

Alternatively, for Debian default repository installations, check /usr/bin/nvcc instead, as those packages install to system directories.

GPG Key or Repository Errors

When apt update shows “GPG error” or signature verification failures for the NVIDIA repository, the GPG key import may have failed. To fix this, remove the existing key and re-import it.

For Debian 13:

sudo rm -f /usr/share/keyrings/nvidia-cuda.gpg
curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/8793F200.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg
sudo apt update

On Debian 12:

sudo rm -f /usr/share/keyrings/nvidia-cuda.gpg
curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/3bf863cc.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg
sudo apt update

On Debian 11:

sudo rm -f /usr/share/keyrings/nvidia-cuda.gpg
curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/debian11/x86_64/3bf863cc.pub | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-cuda.gpg
sudo apt update

Dependency Errors During Installation

When installation fails with “broken packages” or unmet dependencies, ensure the contrib and non-free repositories are properly enabled. To diagnose, check your sources configuration:

On Debian 13 and 12:

grep Components /etc/apt/sources.list.d/debian.sources

The output should include contrib non-free non-free-firmware. If not, run the sed command from the Pre-Installation Steps section again, then:

sudo apt update
sudo apt install -f
sudo apt install cuda nvidia-driver

On Debian 11:

grep -E 'contrib|non-free' /etc/apt/sources.list

Each repository line should include contrib non-free. If not, run the sed command from the Pre-Installation Steps section again.

Nouveau Driver Still Loaded

If the Nouveau open-source driver remains active after NVIDIA driver installation, the two drivers will conflict. Check whether Nouveau is loaded:

lsmod | grep nouveau

If Nouveau modules appear in the output, blacklist the driver and rebuild the initial ramdisk:

echo "blacklist nouveau" | sudo tee /etc/modprobe.d/nvidia-blacklist.conf
sudo update-initramfs -u
sudo reboot

After rebooting, verify that lsmod | grep nouveau produces no output and that lsmod | grep nvidia shows the NVIDIA modules.

Conclusion

Your Debian system now runs a complete CUDA development environment with the nvcc compiler, GPU-accelerated libraries, and NVIDIA drivers ready for parallel computing workloads. Choose the Debian default repository for production stability or the NVIDIA repository for access to the latest toolkit features. To continue learning, explore the NVIDIA CUDA Samples repository or set up machine learning frameworks like PyTorch or TensorFlow that can leverage your GPU acceleration.

Remove CUDA and NVIDIA Drivers

If you need to uninstall CUDA from your Debian system, remove the packages and clean up any repository configuration you added.

Uninstall Packages

Remove all CUDA and NVIDIA packages:

sudo apt remove 'cuda*' 'nvidia*' --purge
sudo apt autoremove --purge

The --purge flag removes configuration files, and autoremove cleans up orphaned dependencies that were installed alongside CUDA but are no longer needed.

Remove the NVIDIA Repository

If you added the NVIDIA CUDA repository, remove the repository file and GPG key:

sudo rm -f /etc/apt/sources.list.d/nvidia-cuda.sources /etc/apt/sources.list.d/nvidia-cuda.list
sudo rm -f /usr/share/keyrings/nvidia-cuda.gpg
sudo apt update

Verify Removal

Confirm CUDA is no longer installed:

nvcc --version

Expected output confirming removal:

bash: nvcc: command not found

You can also verify that the CUDA packages are no longer available from the NVIDIA repository:

apt-cache policy cuda

Expected output after successful removal and repository cleanup:

N: Unable to locate package cuda

If the output instead shows version information with the NVIDIA repository URL, the repository file was not removed correctly. Re-run the repository removal commands and then run sudo apt update before checking again.