Saltar al contenido
La guía completa para corregir problemas de instalación de CUDA

La guía completa para corregir problemas de instalación de CUDA

, 12 min de lectura, By Jaber Jaber

Research

Si estás empezando con el desarrollo en CUDA, probablemente ya encontraste problemas frustrantes de instalación. Analicé cientos de experiencias de desarrolladores y reuní esta guía completa para ayudarte a superar los desafíos de instalación de CUDA más comunes.

A todo desarrollador de CUDA le ha pasado: instalas el toolkit, todo se ve bien, y entonces nvcc --version devuelve "command not found". O peor: todo funciona en tu máquina pero falla en la GPU de otra persona. Tras ayudar a docenas de equipos a depurar estos problemas, he visto los mismos fallos una y otra vez.

Esta guía cubre todos los problemas principales de instalación de CUDA y cómo corregirlos exactamente. Se acabó el ensayo y error.

Tabla de contenido

Problemas comunes:

  • Problemas de PATH y variables de entorno

  • Desajustes de versión entre driver y toolkit

  • Problemas específicos de WSL2

  • Problemas de Secure Boot y UEFI

  • Dependencias de paquetes rotas

  • Instalación y compatibilidad de cuDNN

  • PyTorch CUDA not available

  • Problemas específicos de Windows

  • Instalaciones incompletas

Buenas prácticas para prevenirlos


1. Problemas de PATH y variables de entorno

Problema: nvcc --version devuelve "command not found"

Este es el problema más común tras instalar CUDA. El toolkit está instalado, pero el sistema no encuentra el compilador de CUDA.

Causa raíz: los binarios de CUDA no están en la variable de entorno PATH de tu sistema.

┌──────────────────────────────────────────────────────────────┐
│  Diagnosis Flow                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  $ nvcc --version                                            │
│  → "command not found"                                       │
│                                                              │
│  $ which nvcc                                                │
│  → (empty)                                                   │
│                                                              │
│  $ ls /usr/local/cuda/bin/nvcc                               │
│  → File exists! ✓                                            │
│                                                              │
│  Conclusion: CUDA is installed, PATH is wrong                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solución para Linux/Ubuntu:

Shell
# Add these lines to your ~/.bashrc file
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

# For specific CUDA versions (e.g., CUDA 11.8):
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

# Apply the changes
source ~/.bashrc

Solución para Windows:

  1. Abre Propiedades del sistema → Opciones avanzadas → Variables de entorno

  2. Agrega a PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin

  3. Crea la nueva variable CUDA_PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8

  4. Reinicia tu terminal o IDE

Verificación:

Shell
nvcc --version
which nvcc  # Linux/Mac only

2. Desajustes de versión entre driver y toolkit

Problema: "CUDA driver version is insufficient" o errores de versión incompatible

Causa raíz: tu driver de NVIDIA no admite la versión del toolkit de CUDA que instalaste, o hay un desajuste entre los distintos componentes de CUDA.

Entendiendo las versiones de CUDA:

  • nvidia-smi muestra la versión máxima de CUDA que tu driver admite

  • nvcc --version muestra la versión del toolkit instalada

  • Pueden ser distintas, y eso suele estar bien (el driver admite toolkits más antiguos)

┌──────────────────────────────────────────────────────────────┐
│  CUDA Compatibility Matrix                                   │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  CUDA Toolkit    →    Minimum Driver Version                 │
│  ────────────────────────────────────────────────            │
│  CUDA 12.x              ≥ 525.60.13 (Linux)                  │
│                         ≥ 527.41 (Windows)                   │
│                                                              │
│  CUDA 11.x              ≥ 450.80.02 (Linux)                  │
│                         ≥ 452.39 (Windows)                   │
│                                                              │
│  CUDA 10.x              ≥ 410.48 (Linux)                     │
│                         ≥ 411.31 (Windows)                   │
│                                                              │
│  Rule: Driver version ≥ Toolkit requirement                  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solución 1: actualiza tu driver

Shell
# Ubuntu/Debian
sudo ubuntu-drivers devices  # Check available drivers
sudo ubuntu-drivers autoinstall  # Install recommended driver
# OR
sudo apt install nvidia-driver-535  # Install specific version

# Verify
nvidia-smi

Solución 2: instala una versión de CUDA compatible

Si no puedes actualizar el driver, instala un toolkit de CUDA más antiguo que coincida con la versión de tu driver. Consulta la matriz de compatibilidad de CUDA.

Solución 3: corrige el desajuste de NVML entre driver y librería

Este error suele aparecer tras actualizar el driver:

Shell
# The simplest solution: reboot your system
sudo reboot

# If reboot doesn't work, reload the driver
sudo rmmod nvidia_uvm
sudo rmmod nvidia_drm
sudo rmmod nvidia_modeset
sudo rmmod nvidia
sudo modprobe nvidia

3. Problemas específicos de WSL2

Problema: CUDA no funciona en WSL2 en Windows

WSL2 tiene requisitos propios para el soporte de CUDA que difieren de las instalaciones nativas de Linux.

┌──────────────────────────────────────────────────────────────┐
│  WSL2 CUDA Architecture (Critical Rules)                     │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Windows Host                                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  NVIDIA Driver (WSL-enabled)  ← Install HERE           │  │
│  │  ├─ Manages GPU hardware                               │  │
│  │  └─ Exposes /dev/dxg to WSL2                           │  │
│  └────────────────────────────────────────────────────────┘  │
│         │                                                    │
│         ↓ (passthrough)                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  WSL2 Ubuntu                                           │  │
│  │  ├─ CUDA Toolkit ONLY  ← Install HERE                  │  │
│  │  ├─ NO driver installation!                            │  │
│  │  └─ Uses Windows driver via /dev/dxg                   │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  Common mistake: Installing NVIDIA driver in WSL2            │
│  Result: Conflicts and failures                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Reglas críticas para WSL2:

  1. NO instales drivers de NVIDIA dentro de WSL2: vienen de Windows

  2. Instala solo el CUDA Toolkit en WSL2, no el driver

  3. Windows debe tener el driver de NVIDIA compatible con WSL2

Solución:

Paso 1: instala el driver correcto de Windows Descarga el driver con soporte CUDA para WSL desde la página WSL de NVIDIA.

Paso 2: verifica que WSL2 ve la GPU

Shell
# In WSL2 terminal
nvidia-smi

Si esto funciona, el driver de Windows está configurado correctamente.

Paso 3: instala el CUDA Toolkit en WSL2

Shell
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt-get update
sudo apt-get install cuda-toolkit-12-1  # No driver installation!

Paso 4: define las variables de entorno

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

Problemas comunes de WSL2:

Problema: "GPU not detected in WSL2"

  • Asegúrate de que Windows tiene el driver habilitado para WSL2

  • Revisa la versión del kernel de WSL: wsl cat /proc/version (necesitas ≥ 5.10.43.3)

  • Actualiza WSL: wsl --update en PowerShell

Problema: versiones de CUDA incompatibles

  • Usa solo CUDA 11.0 o superior en WSL2

  • No mezcles instalaciones de CUDA hechas por métodos distintos


4. Problemas de Secure Boot y UEFI

Problema: "Required key not available" o drivers que no cargan con Secure Boot

Causa raíz: el Secure Boot de UEFI impide cargar módulos del kernel sin firmar, incluidos los drivers de NVIDIA.

Solución 1: desactiva Secure Boot (lo más fácil)

  1. Reinicia y entra a la BIOS/UEFI (normalmente DEL, F2 o F12 durante el arranque)

  2. Ve a los ajustes de Seguridad o de Arranque

  3. Desactiva Secure Boot

  4. Guarda y sal

  5. Reinicia en Linux

Solución 2: firma los módulos de NVIDIA (mantén Secure Boot activado)

Shell
# Generate MOK (Machine Owner Key)
openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der -nodes -days 36500 -subj "/CN=Custom MOK/"

# Enroll the key
sudo mokutil --import MOK.der
# You'll be prompted to create a password

# Reboot: you'll see MOK Manager
# Select "Enroll MOK" → "Continue" → "Yes"
# Enter the password you created
# Reboot again

# Now sign the NVIDIA modules
sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 ./MOK.priv ./MOK.der $(modinfo -n nvidia)

Solución 3: usa el firmado integrado de DKMS (Ubuntu 18.04 o superior)

Shell
# During NVIDIA driver installation, you'll be prompted to create a password
# After reboot, MOK Manager appears automatically
# Select "Enroll MOK" and enter your password

Verificación:

Shell
# Check if driver is loaded
lsmod | grep nvidia

# If loaded, secure boot is working with signed modules
mokutil --sb-state  # Should show "SecureBoot enabled"

5. Dependencias de paquetes rotas

Problema: "Unable to correct problems, you have held broken packages" o fallos de apt-get

Esto suele ocurrir cuando las instalaciones de CUDA entran en conflicto con paquetes existentes o con instalaciones previas incompletas.

Diagnóstico:

Shell
sudo apt-get install -f  # Attempt to fix
sudo dpkg --configure -a  # Configure unconfigured packages
apt-cache policy cuda  # Check available versions

Solución 1: empezar de cero

Shell
# Remove all CUDA and NVIDIA packages
sudo apt-get remove --purge '^nvidia-.*'
sudo apt-get remove --purge '^cuda-.*'
sudo apt-get remove --purge '^libnvidia-.*'
sudo apt-get autoremove
sudo apt-get autoclean

# Remove CUDA repository configurations
sudo rm /etc/apt/sources.list.d/cuda*
sudo rm /etc/apt/sources.list.d/nvidia*

# Clean apt cache
sudo apt-get clean

# Update package lists
sudo apt-get update

# Now reinstall from scratch

Solución 2: corrige conflictos de dependencias específicos

Shell
# If apt tells you a specific package is problematic
sudo dpkg --purge --force-all package-name

# Use aptitude for better dependency resolution
sudo apt-get install aptitude
sudo aptitude install cuda

# Aptitude will offer solutions: accept the one that installs/updates packages

Solución 3: maneja conflictos de "archivo ya existente"

Shell
# If error says "trying to overwrite '/path/to/file'"
# Find which package owns the conflicting file
dpkg -S /path/to/file

# Remove that package first
sudo apt-get remove conflicting-package

# Then continue with installation

Para problemas persistentes:

Shell
# Use local installer instead of apt
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --samples --silent

6. Instalación y compatibilidad de cuDNN

Problema: versión de cuDNN incompatible o "cannot find cuDNN"

Causa raíz: los frameworks de aprendizaje profundo requieren versiones específicas de cuDNN que deben coincidir con tu versión de CUDA.

┌──────────────────────────────────────────────────────────────┐
│  CUDA ↔ cuDNN Compatibility Matrix                           │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  CUDA Version    →    Compatible cuDNN Versions              │
│  ────────────────────────────────────────────────────────    │
│  CUDA 12.4              cuDNN 9.x                            │
│  CUDA 12.1              cuDNN 8.9+                           │
│  CUDA 11.8              cuDNN 8.6 to 8.9                     │
│  CUDA 11.x              cuDNN 8.x                            │
│                                                              │
│  Framework requirements:                                     │
│  • PyTorch 2.0+:     cuDNN 8.5+                              │
│  • TensorFlow 2.13+: cuDNN 8.6+                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solución 1: instala cuDNN compatible con apt (Ubuntu)

Shell
# Check your CUDA version
nvcc --version

# For CUDA 11.8
sudo apt-get install libcudnn8=8.9.7.*-1+cuda11.8
sudo apt-get install libcudnn8-dev=8.9.7.*-1+cuda11.8

# For CUDA 12.x
sudo apt-get install libcudnn9-cuda-12

Solución 2: instalación manual

  1. Descarga cuDNN desde la página de cuDNN de NVIDIA (requiere cuenta gratuita)

  2. Elige la versión que coincida con tu toolkit de CUDA

  3. Extrae y copia los archivos:

Shell
tar -xvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz
cd cudnn-linux-x86_64-8.9.7.29_cuda12-archive

# Copy files to CUDA installation
sudo cp include/cudnn*.h /usr/local/cuda/include
sudo cp lib/libcudnn* /usr/local/cuda/lib64
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

Verificación:

Shell
# Check cuDNN version
cat /usr/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

# Or
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

Solución 3: varias versiones de cuDNN con Conda

Shell
# Create isolated environment
conda create -n myenv python=3.10
conda activate myenv

# Install specific CUDA and cuDNN
conda install -c conda-forge cudatoolkit=11.8 cudnn=8.9.2

Error común: "Loaded runtime CuDNN library X but source was compiled with Y"

Esto significa que tu paquete de Python espera una versión distinta de cuDNN.

Corrección:

Shell
# Option 1: Reinstall the package with matching cuDNN
pip uninstall tensorflow-gpu  # or pytorch
pip install tensorflow-gpu==2.15.0  # Version compatible with your cuDNN

# Option 2: Install the expected cuDNN version
sudo apt-get install libcudnn8=X.X.X.*-1+cudaY.Y  # Match the expected version

7. PyTorch CUDA Not Available

Problema: torch.cuda.is_available() devuelve False

Este es uno de los problemas más frustrantes para desarrolladores de aprendizaje profundo.

Pasos de diagnóstico:

Python
import torch
print(torch.__version__)
print(torch.cuda.is_available())
print(torch.version.cuda)  # CUDA version PyTorch was built with

# Try to create a CUDA tensor (provides better error messages)
try:
    torch.zeros(1).cuda()
except Exception as e:
    print(f"Error: {e}")
┌──────────────────────────────────────────────────────────────┐
│  PyTorch CUDA Troubleshooting Decision Tree                  │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  torch.cuda.is_available() == False                          │
│         │                                                    │
│         ├─→ pip list | grep torch shows "+cpu"?              │
│         │   └─→ YES: Installed CPU-only version              │
│         │       FIX: Reinstall with CUDA support             │
│         │                                                    │
│         ├─→ nvidia-smi fails?                                │
│         │   └─→ YES: Driver problem                          │
│         │       FIX: Install/update NVIDIA driver            │
│         │                                                    │
│         ├─→ torch.version.cuda > nvidia-smi CUDA?            │
│         │   └─→ YES: Driver doesn't support PyTorch CUDA     │
│         │       FIX: Upgrade driver or use older PyTorch     │
│         │                                                    │
│         └─→ CUDA_VISIBLE_DEVICES set incorrectly?            │
│             └─→ YES: GPU hidden from PyTorch                 │
│                 FIX: Unset or correct the variable           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Causas comunes y soluciones:

Causa 1: instalaste PyTorch solo para CPU

Este es el problema más común. El pip install torch predeterminado instala la versión solo para CPU.

Solución:

Shell
# Uninstall current PyTorch
pip uninstall torch torchvision torchaudio

# Install with CUDA support (check pytorch.org for your CUDA version)
# For CUDA 11.8:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Causa 2: la versión de CUDA de PyTorch no coincide con el driver

PyTorch incluye su propio runtime de CUDA, pero tu driver debe admitirlo.

Solución:

Shell
# Check driver version
nvidia-smi  # Look at "Driver Version" and "CUDA Version"

# Install PyTorch version compatible with your driver
# If driver supports CUDA 11.8, install PyTorch with CUDA 11.8
# If driver supports CUDA 12.1+, you can use any lower CUDA version

Causa 3: compute capability equivocada

Las GPUs más antiguas pueden no ser compatibles con versiones recientes de PyTorch.

Revisa la compute capability de la GPU:

Shell
# Method 1
nvidia-smi --query-gpu=compute_cap --format=csv

# Method 2 (if you can import torch)
python -c "import torch; print(torch.cuda.get_device_capability())"

Solución:

  • Compute capability menor que 3.5: no admitida por PyTorch moderno

  • Compute capability 3.5 a 5.2: puede necesitar versiones más antiguas de PyTorch

  • Compute capability 5.0 o superior: totalmente admitida

Si tu GPU es demasiado antigua, considera:

Shell
# Install older PyTorch version (e.g., 1.7.1 for older GPUs)
pip install torch==1.7.1+cu101 torchvision==0.8.2+cu101 -f https://download.pytorch.org/whl/torch_stable.html

Causa 4: problemas de entorno o Conda

Solución:

Shell
# Create fresh environment
conda create -n pytorch_env python=3.10
conda activate pytorch_env

# Install PyTorch through conda (often more reliable)
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

Causa 5: CUDA_VISIBLE_DEVICES está mal definida

Shell
# Check if the variable is hiding your GPU
echo $CUDA_VISIBLE_DEVICES

# If it's set to empty or wrong value, unset it
unset CUDA_VISIBLE_DEVICES

# Or set it correctly (0 for first GPU)
export CUDA_VISIBLE_DEVICES=0

Guion rápido de diagnóstico:

Python
# Run this diagnostic script
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"Number of GPUs: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"GPU Name: {torch.cuda.get_device_name(0)}")
    print(f"GPU Compute Capability: {torch.cuda.get_device_capability(0)}")

8. Problemas específicos de Windows

Problema: "Cannot find compiler 'cl.exe' in PATH"

Causa raíz: CUDA en Windows requiere el compilador de C++ de Microsoft Visual Studio (cl.exe), que no viene en el toolkit de CUDA.

┌──────────────────────────────────────────────────────────────┐
│  Windows CUDA Build Requirements                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  CUDA Toolkit alone is NOT enough on Windows!                │
│                                                              │
│  Required components:                                        │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ 1. CUDA Toolkit (nvcc, libraries)                      │  │
│  │ 2. Visual Studio with C++ tools (cl.exe)               │  │
│  │ 3. Windows SDK                                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  CUDA and VS Compatibility:                                  │
│  • CUDA 12.5+:  VS 2019 16.11 to VS 2022 17.10               │
│  • CUDA 12.0-12.4: VS 2019 16.11 to VS 2022 17.7             │
│  • CUDA 11.8:   VS 2019 16.11 to VS 2022 17.0                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solución:

Paso 1: instala Visual Studio

  1. Descarga Visual Studio Community (gratis)

  2. Durante la instalación, elige "Desarrollo de escritorio con C++"

  3. Asegúrate de que estén marcados estos componentes:

    • Herramientas de compilación de C++ MSVC v143 (o la más reciente)

    • Windows SDK

    • Herramientas de CMake para C++

Paso 2: verifica la instalación

Command Prompt
# Open "Developer Command Prompt for VS"
where cl.exe
cl.exe

Paso 3: agrégalo al PATH (si hace falta)

Si cl.exe no se encuentra en el Símbolo del sistema normal:

  1. Busca la ubicación de cl.exe (normalmente):

    Text
    C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.XX.XXXXX\bin\Hostx64\x64
  2. Agrégalo al PATH del sistema o usa el Símbolo del sistema para desarrolladores de Visual Studio

Paso 4: verifica que CUDA encuentra el compilador

Command Prompt
nvcc --version
nvcc test.cu  # Try compiling a simple CUDA file

Problemas comunes de compatibilidad con VS:

Si tienes VS 2022 17.10 o superior con CUDA 12.4 o anterior:

Command Prompt
# Option 1: Upgrade CUDA to 12.5+
# Option 2: Add this flag when compiling
nvcc -allow-unsupported-compiler your_file.cu

# Option 3: Downgrade VS to 17.9
# Option 4: Use flag in CMake
set CMAKE_CUDA_FLAGS=-allow-unsupported-compiler

Problema: conflictos con GeForce Experience (Windows)

Solución:

Al instalar CUDA en Windows, usa Instalación personalizada y desmarca:

  • GeForce Experience (si ya está instalado)

  • Display Driver (si ya tienes un driver que funciona)

Instala solo:

  • CUDA Toolkit

  • Development tools

  • Documentation


9. Instalaciones incompletas

Problema: avisos de "Incomplete installation" o "Driver not selected"

Síntomas:

  • La instalación termina pero con avisos

  • nvidia-smi funciona pero nvcc no

  • Algunos ejemplos de CUDA no compilan

Solución 1: instalación solo del toolkit (cuando el driver ya funciona)

Shell
# Use the runfile installer with toolkit-only flag
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --samples --silent

# Set environment variables
export PATH=/usr/local/cuda-12.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

Solución 2: reinstalación completa

Shell
# Complete cleanup
sudo apt-get remove --purge '^nvidia-.*'
sudo apt-get remove --purge '^cuda-.*'
sudo apt-get autoremove

# Remove any manual installations
sudo rm -rf /usr/local/cuda*

# Reboot
sudo reboot

# Fresh installation using recommended method
sudo apt-get update
sudo apt-get install cuda-toolkit-12-1 nvidia-driver-535

Solución 3: corrige los componentes que falten

Si solo faltan componentes específicos:

Shell
# Install missing samples
sudo apt-get install cuda-samples-12-1

# Install missing libraries
sudo apt-get install cuda-libraries-12-1

# Install development files
sudo apt-get install cuda-libraries-dev-12-1

10. Buenas prácticas

Prevenir es mejor que curar

┌──────────────────────────────────────────────────────────────┐
│  The Right Way to Install CUDA                               │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Step 1: Plan                                                │
│  • Check GPU compute capability                              │
│  • Verify OS and kernel version                              │
│  • Research framework requirements                           │
│  • Pick compatible versions                                  │
│                                                              │
│  Step 2: Clean                                               │
│  • Remove old installations completely                       │
│  • Clean package manager cache                               │
│  • Reboot if needed                                          │
│                                                              │
│  Step 3: Install (in order)                                  │
│  1. NVIDIA Driver                                            │
│  2. CUDA Toolkit                                             │
│  3. cuDNN                                                    │
│  4. Framework (PyTorch/TensorFlow)                           │
│                                                              │
│  Step 4: Verify                                              │
│  • Test nvidia-smi                                           │
│  • Test nvcc --version                                       │
│  • Compile and run deviceQuery                               │
│  • Test framework GPU access                                 │
│                                                              │
│  Step 5: Document                                            │
│  • Save your working environment                             │
│  • Record all version numbers                                │
│  • Keep notes for future reference                           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Antes de instalar:

  1. Revisa la compatibilidad

    • Compute capability de la GPU

    • Versión del sistema operativo y del kernel

    • Requisitos del driver

    • Requisitos del framework (versiones de PyTorch/TensorFlow)

  2. Limpia las instalaciones existentes

    Shell
    sudo apt-get remove --purge '^nvidia-.*' '^cuda-.*'
    sudo apt-get autoremove
  3. Usa fuentes oficiales

    • Descarga desde nvidia.com, no de repositorios de terceros

    • Verifica las sumas de verificación

    • Sigue la guía oficial de instalación para tu sistema

Durante la instalación:

  1. Instala en el orden correcto

    • Primero el driver (o deja que el instalador de CUDA lo maneje)

    • Segundo el CUDA Toolkit

    • Tercero cuDNN

    • Al final el framework (PyTorch/TensorFlow)

  2. Usa instaladores locales para mayor estabilidad

    • Los instaladores de red pueden fallar o traer versiones equivocadas

    • Los runfiles locales te dan más control

  3. Anota tus versiones

    Shell
    # Save this info for troubleshooting
    nvidia-smi
    nvcc --version
    cat /usr/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

Después de la instalación:

  1. Verifica todo

    Shell
    # Driver
    nvidia-smi
    
    # Toolkit
    nvcc --version
    
    # Test compilation
    cd /usr/local/cuda/samples/1_Utilities/deviceQuery
    sudo make
    ./deviceQuery
  2. Crea una copia de seguridad del entorno

    Shell
    # Save your working environment
    conda env export > working_cuda_env.yml
    
    # Or with pip
    pip freeze > requirements.txt
  3. Documenta tu configuración Guarda un registro de:

    • Modelo de GPU

    • Versión del driver

    • Versión de CUDA

    • Versión de cuDNN

    • Versiones del framework

    • Sistema operativo y versión del kernel

Rutas de instalación recomendadas:

Para principiantes:

Shell
# Ubuntu: Use apt packages (easiest)
sudo apt-get update
sudo apt-get install nvidia-driver-535
sudo apt-get install cuda-toolkit-12-1

Para usuarios avanzados:

Shell
# Use runfile for maximum control
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

Para aprendizaje profundo:

Shell
# Use Docker containers (most reliable)
docker pull nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04

# Or use Conda for isolated environments
conda create -n ml_env python=3.10
conda activate ml_env
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia

Cuando algo sale mal:

  1. No instales en pánico

    • Instalar varias versiones no arregla los problemas

    • Limpia primero y luego reinstala

  2. Lee los mensajes de error con cuidado

    • La mayoría de los errores te dicen exactamente qué está mal

    • Busca el mensaje de error específico en Google

  3. Revisa los registros

    Shell
    # CUDA installer logs
    cat /var/log/cuda-installer.log
    
    # System logs
    dmesg | grep -i nvidia
    journalctl -xe | grep -i nvidia
  4. Pide ayuda como corresponde Al publicar en foros, incluye:

    • Sistema operativo y versión

    • Modelo de GPU

    • La salida de nvidia-smi

    • La salida de nvcc --version

    • Los mensajes de error completos

    • Lo que ya has intentado


Lista rápida de diagnóstico

Usa esta lista cuando CUDA no funciona:

┌──────────────────────────────────────────────────────────────┐
│  CUDA Troubleshooting Checklist                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  □ nvidia-smi shows GPU?                                     │
│    → If no: Driver issue                                     │
│                                                              │
│  □ nvcc --version works?                                     │
│    → If no: PATH issue                                       │
│                                                              │
│  □ CUDA version compatible with driver?                      │
│    → Check compatibility matrix                              │
│                                                              │
│  □ cuDNN installed and compatible?                           │
│    → Check version matching                                  │
│                                                              │
│  □ PyTorch/TensorFlow sees GPU?                              │
│    → Check framework installation                            │
│                                                              │
│  □ Secure Boot disabled (or modules signed)?                 │
│    → Check boot settings                                     │
│                                                              │
│  □ All environment variables set?                            │
│    → Check PATH, LD_LIBRARY_PATH, CUDA_HOME                  │
│                                                              │
│  □ On WSL2?                                                  │
│    → Follow WSL2-specific guide                              │
│                                                              │
│  □ On Windows?                                               │
│    → Visual Studio installed?                                │
│                                                              │
│  □ Package dependencies clean?                               │
│    → Run apt --fix-broken install                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Conclusión

La instalación de CUDA puede ser complicada, pero la mayoría de los problemas caen en estas categorías comunes. La clave es:

  1. Identificar el problema específico con los mensajes de error

  2. Entender la causa raíz (desajuste de versión, dependencias faltantes, etc.)

  3. Aplicar la solución dirigida en lugar de reinstalar todo

  4. Verificar la corrección con pruebas adecuadas

Recuerda: una instalación de CUDA que funciona requiere:

  • Hardware de GPU compatible

  • El driver de NVIDIA correcto

  • El CUDA Toolkit

  • Las variables de entorno correctas

  • (Para aprendizaje profundo) cuDNN compatible

  • (Para aprendizaje profundo) El framework instalado con soporte CUDA

Si sigues atascado tras probar estas soluciones, la comunidad de CUDA en los foros de desarrolladores de NVIDIA y Stack Overflow son recursos excelentes.


Última actualización: octubre de 2025