How to Install CUDA on Debian Linux

CUDA (Compute Unified Device Architecture) lets Debian systems offload parallel workloads to NVIDIA GPUs for machine learning, video processing, and scientific computing. Additionally, the toolkit ships nvcc, Nsight profiling tools, and GPU-accelerated libraries such as cuBLAS, cuDNN, and cuFFT that plug into frameworks like PyTorch and TensorFlow.

This guide covers two installation methods: Debian’s default repositories for stability-focused production 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.

Choose Your CUDA Installation Method

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

Method	Debian Version Support	Stability	Best For
Debian Default Repository	Debian 13, 12, 11 (x86_64)	High stability, conservative updates, thorough distribution testing	Production environments, users prioritizing stability over latest features
NVIDIA CUDA 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, users needing newest GPU features and libraries

For most users, the NVIDIA CUDA Repository is recommended because it provides the latest CUDA versions and driver updates. The default Debian repository is best for production environments where stability matters more than having cutting-edge features. Check the official NVIDIA CUDA repository directory to verify architecture support for your specific Debian version.

The default Debian repository delivers CUDA packages that undergo extensive distribution testing, making it ideal for production environments requiring proven stability. In contrast, the NVIDIA CUDA repository provides immediate access to the latest CUDA toolkit versions, GPU-accelerated libraries, and performance optimizations as soon as NVIDIA releases them, at the cost of reduced integration testing before reaching your system.

For machine learning development and CUDA application work, the NVIDIA CUDA repository offers the best access to current features and libraries. On the other hand, production environments with strict change management policies should use Debian’s default repositories for proven stability and support lifecycle integration.

Clean Up Previous NVIDIA Installations

Skip this section if you’re installing CUDA on a clean Debian system for the first time. However, use this section only if you’re upgrading CUDA versions, reinstalling after failed installation, switching from Nouveau drivers, or removing a previous runfile installation.

Method 1: Uninstalling NVIDIA Packages Installed via APT

If you’ve previously used the APT package manager to install NVIDIA drivers, remove all NVIDIA and CUDA packages without expanding unintended shell globs:

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

Update your package cache after removal:

sudo apt update

Method 2: Uninstalling NVIDIA Drivers Installed via Runfile

If you’ve installed NVIDIA drivers using a .run file (generally not recommended due to better alternatives like the NVIDIA CUDA repository), a different approach is needed for its removal.

First, to remove the runfile type of installation, execute the following command:

sudo /usr/bin/nvidia-uninstall

This command runs the nvidia-uninstall script that comes with the runfile installation. Subsequently, the script methodically removes the NVIDIA driver that was installed using the runfile.

Method 3: Uninstalling CUDA Toolkit Installed via Runfile

If you’ve installed the CUDA toolkit using a runfile, it’s also essential to remove this. Similarly, the removal process is similar to that of the NVIDIA drivers. To remove the CUDA toolkit, execute the following command:

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

In the above command, replace X.Y with the version number of your installed CUDA toolkit. Once executed, this command runs the cuda-uninstall script, which is included in the runfile installation of the CUDA toolkit. The script is designed to remove the CUDA toolkit methodically from your Debian system.

Pre-Installation Steps

Update System Packages

Update your package index and upgrade existing packages to ensure kernel headers and dependencies match your current system state:

sudo apt update

Next, proceed to upgrade any outdated packages:

sudo apt upgrade

Enable Contrib and Non-Free Repositories

NVIDIA CUDA packages reside in Debian’s non-free repositories due to proprietary licensing. Therefore, before installation, you must enable the contrib and non-free repositories. Additionally, the command syntax changed in Debian 12 Bookworm with the introduction of the non-free-firmware component, so ensure you use the correct command for your Debian version.

First, install the required packages for repository management and GPG key handling:

sudo apt install software-properties-common curl gnupg -y

Then, for Debian 12 Bookworm and newer releases (including Debian 13 Trixie):

sudo add-apt-repository contrib non-free non-free-firmware

For Debian 11 Bullseye:

sudo add-apt-repository contrib non-free

Update your APT cache to reflect the newly enabled repositories:

sudo apt update

Method 1: Install CUDA from Debian Default Repository (Debian x86_64)

The Debian default repository provides CUDA packages for all supported Debian x86_64 systems. This method delivers tested stability and long-term distribution support, making it the recommended choice for production environments where consistent behavior across updates matters more than having the absolute latest CUDA version.

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

sudo apt install nvidia-cuda-toolkit nvidia-driver

This command installs the CUDA compiler (nvcc), libraries, headers, and matching NVIDIA drivers tested for your Debian version. Additionally, the nvidia-cuda-toolkit package includes cuBLAS, cuFFT, cuSPARSE, and other GPU-accelerated libraries needed for CUDA development.

Debian’s packages place nvcc in /usr/bin and the libraries under /usr/lib/x86_64-linux-gnu, so PATH and library variables are already set by default. As a result, you can skip the CUDA environment variable section unless you later switch to the NVIDIA repository.

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

sudo reboot

Debian’s default repository packages are slightly older than NVIDIA’s direct releases but receive thorough testing for distribution compatibility. If you need the newest CUDA features, continue to Method 2 (NVIDIA CUDA Repository) instead.

Method 2: Install CUDA from NVIDIA Repository

The NVIDIA CUDA repository provides the newest CUDA toolkit and driver releases for Debian 13 Trixie, Debian 12 Bookworm, and Debian 11 Bullseye. Both x86_64 and SBSA/ARM64 architectures are supported for Debian 13 and 12, while Debian 11 supports x86_64 only.

Import NVIDIA GPG Key

First, download the NVIDIA GPG key directly into the system keyring. Use the command matching your Debian version and architecture:

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

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

Debian 12 Bookworm:

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

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

Debian 11 Bullseye:

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

This command fetches NVIDIA’s GPG key (in ASCII-armored format) and converts it to binary format for use in APT repository configuration. Debian 13 uses a newer signing key (8793F200.pub) while Debian 11 and 12 share the older key (3bf863cc.pub).

Add NVIDIA CUDA APT Repository

Next, add the NVIDIA CUDA repository using the modern DEB822 format for Debian 13/12 or the legacy format for Debian 11:

Debian 13 Trixie (x86_64):

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

Debian 13 Trixie (SBSA/ARM64):

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

Debian 12 Bookworm:

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

Debian 12 Bookworm (SBSA/ARM64):

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

Debian 12 (Bookworm) and Debian 13 (Trixie) use the modern DEB822 .sources format shown above. Debian 11 (Bullseye) remains supported as oldstable but typically uses the legacy .list format, so if you’re running Debian 11, use the command provided below instead.

Debian 11 Bullseye:

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

Update Package Cache

After adding the repository, update your package cache to reflect the newly added NVIDIA CUDA repository:

sudo apt update

Install CUDA Toolkit and NVIDIA Drivers

Verify Available CUDA Versions

Before proceeding with installation, check the available CUDA versions in the NVIDIA repository:

apt policy cuda

This command shows the CUDA versions available and which repository provides them. For example, expected output on Debian 12 with NVIDIA repo configured:

cuda:
  Installed: (none)
  Candidate: 12.x.x-x
  Version table:
     12.x.x-x 500
        500 https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64  Packages

The candidate version is what APT will install. Additionally, verify the NVIDIA repository URL appears in the version table; if it doesn’t, the repository wasn’t added correctly.

Install CUDA Toolkit with NVIDIA Drivers

Once verification completes, install the CUDA toolkit metapackage, which includes the compiler (nvcc), libraries, development headers, and matching NVIDIA drivers:

sudo apt install nvidia-driver cuda

The cuda metapackage automatically installs the latest CUDA version available in the NVIDIA repository, including cuBLAS, cuFFT, cuDNN, Nsight development tools, and compatible NVIDIA drivers. Furthermore, the nvidia-driver metapackage ensures you receive the driver version tested with your CUDA toolkit.

NVIDIA drivers include proprietary firmware and closed-source components necessary for full GPU functionality. The drivers integrate with DKMS (Dynamic Kernel Module Support), which automatically rebuilds kernel modules when you install kernel updates, maintaining driver functionality across kernel upgrades without manual intervention. For comprehensive driver troubleshooting and standalone driver installation, see the NVIDIA drivers on Debian guide.

Systems with Secure Boot enabled require enrolling a Machine Owner Key (MOK) to load DKMS-built kernel modules. Debian provides detailed instructions for MOK enrollment with DKMS and Secure Boot. Complete MOK enrollment before installing NVIDIA drivers to avoid rebuilding the kernel image. Alternatively, temporarily disable Secure Boot in BIOS/UEFI settings during installation.

Reboot System to Activate Drivers

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

sudo reboot

Verify and Configure Your CUDA Installation

Verify CUDA Installation

Once your system reboots, verify the NVIDIA driver loaded correctly and CUDA recognizes your GPU using nvidia-smi:

nvidia-smi

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

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.xx.xx    Driver Version: 550.xx.xx    CUDA Version: 12.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 installation succeeded and CUDA can access your GPU hardware. The driver and CUDA versions shown in the header match your installed packages.

Next, check the CUDA compiler version to verify the toolkit installed correctly:

nvcc --version

Expected output shows the CUDA toolkit version and compiler details:

nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2024 NVIDIA Corporation
Built on [date]
Cuda compilation tools, release 12.x, V12.x.xxx
Build cuda_12.x.rxx.x/compiler.xxxxxxxx_x

Accordingly, the version number confirms the CUDA toolkit is ready for development.

Configure CUDA Environment Variables

Only configure environment variables if you installed from the NVIDIA repository (which places CUDA under /usr/local/cuda). Debian default packages already add /usr/bin to PATH and /usr/lib/x86_64-linux-gnu to the dynamic linker search path.

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

These commands append CUDA paths to your .bashrc file (loaded automatically for interactive login shells) and activate them immediately in the current session. The PATH variable allows running nvcc and other CUDA tools directly. Additionally, the LD_LIBRARY_PATH variable ensures compiled CUDA programs find GPU-accelerated libraries at runtime.

After setting these variables, verify the configuration:

which nvcc

Output should show the path to nvcc (/usr/local/cuda/bin/nvcc for NVIDIA repository installs or /usr/bin/nvcc for Debian default packages):

/usr/local/cuda/bin/nvcc

Creating Your First CUDA Program

Now test your CUDA installation by compiling a basic CUDA program. Create a new file with the .cu extension, which is standard for CUDA source files:

nano helloworld.cu

Next, insert the following code into the file. This straightforward program displays a “Hello, World!” message from the 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>>>();
    cudaDeviceReset();
    return 0;
}

After entering the code, to compile this program, utilize the nvcc command, which stands for NVIDIA CUDA Compiler:

nvcc helloworld.cu -o helloworld

Once compilation completes, run the compiled program:

./helloworld

The output should display the following:

Hello World from CPU!
Hello World from GPU!

Advanced CUDA Programming: Matrix Multiplication

To demonstrate CUDA’s parallel computing capabilities, let’s develop a complete matrix multiplication program. In particular, this example shows how CUDA efficiently handles matrix operations using GPU threads.

First, start by creating a new file:

nano matrixmul.cu

Then, insert the following complete CUDA program into the file:

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

#define CHECK(call) \
do { \
    cudaError_t error = call; \
    if (error != cudaSuccess) { \
        fprintf(stderr, "CUDA error: %s\n", cudaGetErrorString(error)); \
        exit(1); \
    } \
} while(0)

__global__ void gpu_matrix_mult(float *a, float *b, float *c, int m, int n, int k) { 
    int row = blockIdx.y * blockDim.y + threadIdx.y; 
    int col = blockIdx.x * blockDim.x + threadIdx.x;
    
    if (row < m && col < k) {
        float sum = 0.0f;
        for (int j = 0; j < n; j++) {
            sum += a[row * n + j] * b[j * k + col];
        }
        c[row * k + col] = sum;
    }
}

int main() {
    int m = 2, n = 3, k = 2;
    
    // Host arrays
    float h_a[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
    float h_b[] = {7.0, 8.0, 9.0, 10.0, 11.0, 12.0};
    float h_c[4] = {0.0};
    
    // Device arrays
    float *d_a, *d_b, *d_c;
    size_t bytes_a = m * n * sizeof(float);
    size_t bytes_b = n * k * sizeof(float);
    size_t bytes_c = m * k * sizeof(float);
    
    // Allocate device memory
    CHECK(cudaMalloc(&d_a, bytes_a));
    CHECK(cudaMalloc(&d_b, bytes_b));
    CHECK(cudaMalloc(&d_c, bytes_c));
    
    // Copy data to device
    CHECK(cudaMemcpy(d_a, h_a, bytes_a, cudaMemcpyHostToDevice));
    CHECK(cudaMemcpy(d_b, h_b, bytes_b, cudaMemcpyHostToDevice));
    
    // Configure kernel execution
    dim3 blockSize(16, 16);
    dim3 gridSize((k + blockSize.x - 1) / blockSize.x, (m + blockSize.y - 1) / blockSize.y);
    
    // Launch kernel
    gpu_matrix_mult<<<gridSize, blockSize>>>(d_a, d_b, d_c, m, n, k);
    CHECK(cudaGetLastError());
    
    // Copy result back to host
    CHECK(cudaMemcpy(h_c, d_c, bytes_c, cudaMemcpyDeviceToHost));
    
    // Print results
    printf("Result matrix:\n");
    for (int i = 0; i < m; i++) {
        for (int j = 0; j < k; j++) {
            printf("%6.1f ", h_c[i * k + j]);
        }
        printf("\n");
    }
    
    // Free device memory
    CHECK(cudaFree(d_a));
    CHECK(cudaFree(d_b));
    CHECK(cudaFree(d_c));
    
    return 0;
}

After entering the program, compile it using the nvcc command:

nvcc matrixmul.cu -o matrixmul

Once the compilation finishes, execute the compiled program:

./matrixmul

The output displays the result matrix:

Result matrix:
  58.0   64.0 
 139.0  154.0

Overall, this example demonstrates critical CUDA concepts: GPU memory allocation with cudaMalloc, data transfer with cudaMemcpy, kernel launch with grid/block configuration, error checking with cudaGetLastError, and proper cleanup with cudaFree. Additionally, the CHECK macro provides robust error handling for production CUDA applications.

Troubleshooting CUDA Installation Issues

nvidia-smi Not Found or GPU Not Detected

If nvidia-smi returns “command not found” or shows no GPU, first verify the NVIDIA driver loaded correctly:

lsmod | grep nvidia

Expected output when the driver is 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 module didn’t load. In this case, check for errors:

sudo dmesg | grep -i nvidia

Common causes include: Secure Boot blocking unsigned modules, kernel module compilation failure, or incompatible GPU. In such cases, try restarting (some installations require reboot for DKMS to rebuild modules):

sudo reboot

nvcc Command Not Found

If nvcc --version returns “command not found,” the CUDA toolkit PATH isn’t configured. First, verify installation:

ls -la /usr/local/cuda/bin/nvcc

If the file exists but isn’t in PATH, run the environment configuration commands from the section above. However, if the file doesn’t exist, the CUDA toolkit package didn’t install properly. In that case, reinstall:

sudo apt install --reinstall nvidia-cuda-toolkit

APT Repository Key or Signature Errors

If apt update shows “GPG error: … CUDA repository” or “failed to fetch,” the GPG key import failed. To fix this, re-import the key:

Debian 13:

sudo rm /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

Debian 12:

sudo rm /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

Debian 11:

sudo rm /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

CUDA Installation Fails with Dependency Errors

If installation fails with “broken packages” or unmet dependencies, first enable contrib and non-free repositories if not already done:

Debian 12 and Debian 13:

sudo apt install software-properties-common -y
sudo add-apt-repository contrib non-free non-free-firmware
sudo apt update
sudo apt install --fix-broken
sudo apt install nvidia-driver cuda

Debian 11:

sudo apt install software-properties-common -y
sudo add-apt-repository contrib non-free
sudo apt update
sudo apt install --fix-broken
sudo apt install nvidia-driver cuda

Nouveau Driver Still Loaded

If Nouveau drivers are still active, the NVIDIA drivers may not function properly. First, check:

lsmod | grep nouveau

If Nouveau is loaded, you’ll see output similar to:

nouveau              2764800  1
mxm_wmi               16384  1 nouveau
drm_ttm_helper        16384  1 nouveau

No output means Nouveau is not loaded (this is the desired state). If output appears, blacklist Nouveau and reboot:

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

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 applications. Both installation methods provide verified, working CUDA toolkits—choose the default repository for stability or the NVIDIA repository for the latest features. To continue learning, explore PyTorch, TensorFlow, or NVIDIA’s CUDA samples for hands-on GPU programming experience.

Remove CUDA Toolkit and NVIDIA Drivers

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

Uninstall CUDA and NVIDIA Packages

Remove all CUDA and NVIDIA packages installed via APT:

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

The autoremove command removes orphaned dependencies that were installed alongside CUDA but are no longer needed.

Remove NVIDIA Repository (If Added)

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

sudo rm /etc/apt/sources.list.d/nvidia-cuda.sources /etc/apt/sources.list.d/nvidia-cuda.list 2>/dev/null
sudo rm /usr/share/keyrings/nvidia-cuda.gpg
sudo apt update

After removal, verify CUDA is no longer installed:

nvcc --version

Expected output confirms removal:

-bash: nvcc: command not found