
La guía completa para corregir problemas de instalación de CUDA
, 12 min de lectura, By Jaber Jaber
ResearchSi 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:
Solución para Windows:
Abre Propiedades del sistema → Opciones avanzadas → Variables de entorno
Agrega a PATH:
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\binCrea la nueva variable
CUDA_PATH:C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8Reinicia tu terminal o IDE
Verificación:
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-smimuestra la versión máxima de CUDA que tu driver admitenvcc --versionmuestra la versión del toolkit instaladaPueden 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
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:
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:
NO instales drivers de NVIDIA dentro de WSL2: vienen de Windows
Instala solo el CUDA Toolkit en WSL2, no el driver
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
Si esto funciona, el driver de Windows está configurado correctamente.
Paso 3: instala el CUDA Toolkit en WSL2
Paso 4: define las variables de entorno
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 --updateen 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)
Reinicia y entra a la BIOS/UEFI (normalmente DEL, F2 o F12 durante el arranque)
Ve a los ajustes de Seguridad o de Arranque
Desactiva Secure Boot
Guarda y sal
Reinicia en Linux
Solución 2: firma los módulos de NVIDIA (mantén Secure Boot activado)
Solución 3: usa el firmado integrado de DKMS (Ubuntu 18.04 o superior)
Verificación:
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:
Solución 1: empezar de cero
Solución 2: corrige conflictos de dependencias específicos
Solución 3: maneja conflictos de "archivo ya existente"
Para problemas persistentes:
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)
Solución 2: instalación manual
Descarga cuDNN desde la página de cuDNN de NVIDIA (requiere cuenta gratuita)
Elige la versión que coincida con tu toolkit de CUDA
Extrae y copia los archivos:
Verificación:
Solución 3: varias versiones de cuDNN con Conda
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:
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:
┌──────────────────────────────────────────────────────────────┐ │ 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:
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:
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:
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:
Causa 4: problemas de entorno o Conda
Solución:
Causa 5: CUDA_VISIBLE_DEVICES está mal definida
Guion rápido de diagnóstico:
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
Descarga Visual Studio Community (gratis)
Durante la instalación, elige "Desarrollo de escritorio con C++"
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
Paso 3: agrégalo al PATH (si hace falta)
Si cl.exe no se encuentra en el Símbolo del sistema normal:
Busca la ubicación de cl.exe (normalmente):
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
Problemas comunes de compatibilidad con VS:
Si tienes VS 2022 17.10 o superior con CUDA 12.4 o anterior:
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-smifunciona peronvccnoAlgunos ejemplos de CUDA no compilan
Solución 1: instalación solo del toolkit (cuando el driver ya funciona)
Solución 2: reinstalación completa
Solución 3: corrige los componentes que falten
Si solo faltan componentes específicos:
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:
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)
Limpia las instalaciones existentes
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:
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)
Usa instaladores locales para mayor estabilidad
Los instaladores de red pueden fallar o traer versiones equivocadas
Los runfiles locales te dan más control
Anota tus versiones
Después de la instalación:
Verifica todo
Crea una copia de seguridad del entorno
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:
Para usuarios avanzados:
Para aprendizaje profundo:
Cuando algo sale mal:
No instales en pánico
Instalar varias versiones no arregla los problemas
Limpia primero y luego reinstala
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
Revisa los registros
Pide ayuda como corresponde Al publicar en foros, incluye:
Sistema operativo y versión
Modelo de GPU
La salida de
nvidia-smiLa salida de
nvcc --versionLos 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:
Identificar el problema específico con los mensajes de error
Entender la causa raíz (desajuste de versión, dependencias faltantes, etc.)
Aplicar la solución dirigida en lugar de reinstalar todo
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