# HOWTO: Install NVIDIA drivers on Debian 13+/testing/unstable

This guide explains how to install and maintain NVIDIA GPU drivers on Debian 13 (trixie), testing, and unstable using `install-scripts/nvidia.sh`.

Supported scope

- Debian 13 (trixie), Debian testing, Debian unstable.
- Current-generation NVIDIA GPUs are best served by NVIDIA’s own repository (cuda-drivers or nvidia-open). Avoid Debian’s `nvidia-driver` for new cards.

Quick start

```bash
# Interactive (recommended first run)
install-scripts/nvidia.sh

# Install from NVIDIA CUDA repo (proprietary)
install-scripts/nvidia.sh --mode=nvidia

# Install from NVIDIA CUDA repo (open kernel modules)
install-scripts/nvidia.sh --mode=open

# Install Debian-packaged drivers (older; not recommended for new GPUs)
install-scripts/nvidia.sh --mode=debian
```

## What the script does

- Detects your GPU (prefers `nvidia-smi`, falls back to `lspci`).
- Offers three installation paths (see below).
- For NVIDIA repo paths:
    - Ensures the CUDA APT repo/keyring for Debian 13 is configured (idempotent).
    - Installs the selected meta package: `cuda-drivers` (proprietary) or `nvidia-open` (open kernel modules).
- Adds kernel parameters to blacklist nouveau and enable DRM KMS, updates GRUB, and updates initramfs.
- Runs a post-install verification (driver source, module loaded, `nvidia-smi`/OpenGL summary).
- Prints an end-of-run summary of changes.

## Options and when to use them

- NVIDIA CUDA repo — proprietary (`--mode=nvidia`)
    - Installs `cuda-drivers` from NVIDIA’s APT repo. Best compatibility and newest drivers; recommended for RTX 30/40/50 series.
- NVIDIA CUDA repo — open kernel modules (`--mode=open`)
    - Installs `nvidia-open` from NVIDIA’s APT repo. Uses the open-source kernel modules. Consider this if you prefer open modules and your GPU is supported.
- Debian repo — packaged by Debian (`--mode=debian`)
    - Installs `nvidia-driver` and related packages from Debian. Typically older; acceptable for older GPUs, not recommended for current-generation cards.

## Important warnings shown by the script

When run interactively, the script displays this notice:

```
[WARN] Default installs Debian repo NVIDIA drivers (often older).
[WARN] NVIDIA driver options are currently in development.
[WARN] If you have a current‑generation NVIDIA GPU, do NOT use Debian-based drivers.
      Choose an NVIDIA CUDA repo option below, or install drivers manually and re-run the Debian Hyprland install.
[ACTION] Choose installation source:
  [D] Debian repo (default) — installs nvidia-driver and related pkgs
  [N] NVIDIA CUDA repo — installs cuda-drivers (proprietary)
  [O] NVIDIA CUDA repo — installs nvidia-open (open kernel modules)
Select [D/n/o]: _
```

## Non-interactive flags

- `--mode=debian|nvidia|open` Selects installation path.
- `--switch` Switch from your current variant to the target mode (removes conflicting meta-packages).
- `--force` Don’t exit early if already configured; re-run installs.
- `-n, --dry-run` Simulate actions (uses `apt-get -s`, prints changes without applying).
- `-h, --help` Show usage, options, and examples.

Examples

```bash
# Switch from Debian-packaged driver to proprietary CUDA repo driver
install-scripts/nvidia.sh --mode=nvidia --switch

# Re-run Debian path even if already configured
install-scripts/nvidia.sh --mode=debian --force

# Dry-run the open-kernel flow without making changes
install-scripts/nvidia.sh --mode=open --dry-run
```

## Sample outputs

GPU detection

```
[INFO] Detecting NVIDIA GPU...
[OK] Detected (nvidia-smi): NVIDIA GeForce RTX 3050, 590.48.01
```

(If drivers are not yet loaded, it falls back to `lspci` output.)

Post-install verification

```
[INFO] Verifying NVIDIA installation...
[OK] Driver source detected: proprietary (NVIDIA CUDA repo)
[INFO] Kernel module loaded: yes
[OK] nvidia-smi: NVIDIA GeForce RTX 3050, 590.48.01
[INFO] OpenGL summary:
OpenGL vendor string: NVIDIA Corporation
OpenGL renderer string: NVIDIA GeForce RTX 3050/PCIe/SSE2
OpenGL core profile version string: 4.6.0 NVIDIA 590.48.01
```

End-of-run summary

```
[OK] No changes made.
```

Or, when changes occurred:

```
[OK] Changes applied:
 - configured NVIDIA CUDA repo (debian13)
 - apt install: cuda-drivers
 - updated GRUB_CMDLINE_LINUX in /etc/default/grub
 - update-grub
 - update-initramfs -u
```

Early exit when re-running

```
[OK] NVIDIA is already configured for mode: nvidia
[INFO] Use --force to re-run installs, or --switch to change variants.
```

## What gets changed on your system

- APT: Adds/uses NVIDIA’s CUDA repo (Debian 13 path) via `cuda-keyring` (only if missing).
- GRUB: Appends `rd.driver.blacklist=nouveau modprobe.blacklist=nouveau nvidia-drm.modeset=1 rcutree.rcu_idle_gp_delay=1` to `GRUB_CMDLINE_LINUX` and runs `update-grub`.
- Modules: Ensures `nvidia nvidia_modeset nvidia_uvm nvidia_drm` are added to `/etc/initramfs-tools/modules`, then runs `update-initramfs -u`.

All changes are idempotent; re-running won’t duplicate entries. The script prints a clear summary of what, if anything, changed.

## Troubleshooting

- Reboot required: After installing drivers, a reboot is often needed for the `nvidia` kernel module to load.
- `nvidia-smi` missing: If `nvidia-smi` isn’t found right away, ensure the installation completed and reboot.
- Switching variants: Use `--switch` with `--mode=...` to change between Debian, proprietary CUDA, and open kernel module variants; the script removes conflicting meta-packages first.

## Uninstall / switching notes

The meta-packages are mutually exclusive per variant:

- Debian: `nvidia-driver`
- Proprietary CUDA: `cuda-drivers`
- Open modules: `nvidia-open`

When switching, the script purges the conflicting meta-packages and runs `apt autoremove` before installing the target.

---

If you prefer to install drivers manually (outside the script), do so first, then re-run the Debian Hyprland installer, say `No` to installing NVIDIA, to continue with the rest of the setup.