Instalación y Configuración de CUDA Toolkit en Linux

CUDA Toolkit es el entorno de desarrollo de NVIDIA para programación GPU, esencial para ejecutar frameworks de machine learning como TensorFlow y PyTorch, o cualquier aplicación de computación paralela. La versión de CUDA debe ser compatible con el driver NVIDIA instalado y con los frameworks que vayas a usar, por lo que la selección de versión es el paso más crítico. Esta guía cubre la instalación de CUDA Toolkit, cuDNN, la gestión de múltiples versiones y la configuración de las variables de entorno necesarias.

Requisitos Previos

  • Driver NVIDIA instalado y funcionando (nvidia-smi muestra la GPU correctamente)
  • Ubuntu 20.04/22.04 o CentOS/Rocky Linux 8/9
  • GCC y herramientas de compilación instaladas
  • Al menos 5 GB de espacio libre en disco
# Verificar que el driver NVIDIA está correctamente instalado
nvidia-smi

# Anotar la versión del driver (columna "Driver Version")
# y la versión máxima de CUDA soportada (columna "CUDA Version")

Selección de la Versión de CUDA

La versión de CUDA debe ser compatible con:

  1. El driver NVIDIA instalado (el driver establece la versión CUDA máxima)
  2. Los frameworks que vayas a usar (TensorFlow, PyTorch, etc.)

Tabla de compatibilidad de referencia:

Driver NVIDIACUDA máximo soportado
525.xCUDA 12.0
535.xCUDA 12.2
545.xCUDA 12.3
550.xCUDA 12.4

Para PyTorch: Consulta pytorch.org/get-started Para TensorFlow: Consulta tensorflow.org/install/source

# Ver la versión máxima de CUDA soportada por el driver actual
nvidia-smi | grep "CUDA Version"

Instalación de CUDA Toolkit en Ubuntu/Debian

Método 1: Repositorio de red (recomendado)

# Para Ubuntu 22.04 + CUDA 12.2
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update

# Instalar CUDA Toolkit completo (incluye el compilador nvcc)
sudo apt-get install -y cuda-toolkit-12-2

# O instalar solo el toolkit sin el driver (si el driver ya está instalado)
sudo apt-get install -y cuda-toolkit-12-2

Método 2: Instalador local (sin internet en el servidor)

# Descargar el instalador local desde developer.nvidia.com/cuda-downloads
# Seleccionar: Linux > x86_64 > Ubuntu > 22.04 > deb (local)

wget https://developer.download.nvidia.com/compute/cuda/12.2.0/local_installers/cuda-repo-ubuntu2204-12-2-local_12.2.0-535.54.03-1_amd64.deb

sudo dpkg -i cuda-repo-ubuntu2204-12-2-local_12.2.0-535.54.03-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2204-12-2-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get install -y cuda-toolkit-12-2

Instalación solo del compilador nvcc (más ligera)

# Si solo necesitas compilar código CUDA pero no el SDK completo
sudo apt-get install -y cuda-nvcc-12-2

Instalación en CentOS/Rocky Linux

# Añadir el repositorio de CUDA
sudo dnf config-manager --add-repo \
  https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo

sudo dnf clean all

# Instalar CUDA Toolkit
sudo dnf install -y cuda-toolkit-12-2

# O instalar la versión completa (driver + toolkit)
sudo dnf install -y cuda-12-2

Configuración de Variables de Entorno

Las variables de entorno deben configurarse para que el sistema encuentre los binarios y las bibliotecas de CUDA.

# Añadir las variables de entorno al perfil del usuario
cat >> ~/.bashrc << 'EOF'

# Configuración de CUDA Toolkit
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
EOF

# Aplicar los cambios
source ~/.bashrc

# Para que estén disponibles para todos los usuarios (como root)
cat >> /etc/environment << 'EOF'
CUDA_HOME=/usr/local/cuda
EOF

# Crear enlace de la biblioteca compartida
echo "/usr/local/cuda/lib64" | sudo tee /etc/ld.so.conf.d/cuda.conf
sudo ldconfig

Verificar las variables

# Comprobar que nvcc está disponible
which nvcc
nvcc --version

# Salida esperada:
# nvcc: NVIDIA (R) Cuda compiler driver
# Copyright (c) 2005-2023 NVIDIA Corporation
# Built on Tue_Aug_15_22:02:13_PDT_2023
# Cuda compilation tools, release 12.2, V12.2.140

Instalación de cuDNN

cuDNN (CUDA Deep Neural Network library) acelera las redes neuronales y es requerida por TensorFlow y PyTorch.

Instalación desde repositorio (Ubuntu)

# Asegurarse de que el repositorio de CUDA está añadido (paso anterior)
sudo apt-get install -y libcudnn8 libcudnn8-dev libcudnn8-samples

# Verificar la instalación
dpkg -l | grep cudnn

Instalación desde archivo comprimido (todas las distribuciones)

# Descargar cuDNN desde developer.nvidia.com/cudnn (requiere cuenta NVIDIA)
# Seleccionar la versión compatible con tu CUDA

# Ejemplo para cuDNN 8.9 + CUDA 12.x
tar -xzvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz

# Copiar los archivos a la instalación de CUDA
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda/include/
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda/lib64/
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

# Actualizar las bibliotecas compartidas
sudo ldconfig

# Verificar la instalación
cat /usr/local/cuda/include/cudnn_version.h | grep "#define CUDNN_"

Gestión de Múltiples Versiones de CUDA

Cuando necesitas CUDA 11.x para un proyecto y CUDA 12.x para otro, puedes instalar varias versiones y cambiar entre ellas.

# Instalar múltiples versiones (cada una en su propio directorio)
sudo apt-get install -y cuda-toolkit-11-8
sudo apt-get install -y cuda-toolkit-12-2

# Las versiones se instalan en:
ls /usr/local/ | grep cuda
# cuda-11.8
# cuda-12.2
# cuda -> cuda-12.2 (enlace simbólico a la versión activa)

# Cambiar la versión activa actualizando el enlace simbólico
sudo rm /usr/local/cuda
sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda

# Verificar el cambio
nvcc --version

Alternativa: gestión de versiones con update-alternatives (Ubuntu)

# Registrar las instalaciones de nvcc con update-alternatives
sudo update-alternatives --install /usr/bin/nvcc nvcc /usr/local/cuda-11.8/bin/nvcc 118
sudo update-alternatives --install /usr/bin/nvcc nvcc /usr/local/cuda-12.2/bin/nvcc 122

# Seleccionar la versión activa interactivamente
sudo update-alternatives --config nvcc

# Cambiar programáticamente
sudo update-alternatives --set nvcc /usr/local/cuda-12.2/bin/nvcc

Uso con entornos virtuales Python

# La mejor práctica es usar entornos virtuales con la versión de CUDA correcta
python3 -m venv venv-cuda11
source venv-cuda11/bin/activate
pip install tensorflow==2.12.0  # Requiere CUDA 11.x

python3 -m venv venv-cuda12
source venv-cuda12/bin/activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121  # CUDA 12.1

Verificación de la Instalación

# Verificación básica: compilador nvcc
nvcc --version

# Verificación del runtime de CUDA
python3 -c "import ctypes; ctypes.CDLL('libcuda.so.1'); print('CUDA runtime OK')"

# Verificación con PyTorch
python3 -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA disponible: {torch.cuda.is_available()}')
print(f'Versión CUDA: {torch.version.cuda}')
print(f'GPUs: {torch.cuda.device_count()}')
if torch.cuda.is_available():
    print(f'GPU: {torch.cuda.get_device_name(0)}')
"

# Verificación con TensorFlow
python3 -c "
import tensorflow as tf
print(f'TensorFlow: {tf.__version__}')
gpus = tf.config.list_physical_devices('GPU')
print(f'GPUs disponibles: {len(gpus)}')
for gpu in gpus:
    print(f'  - {gpu}')
"

# Compilar y ejecutar el ejemplo de suma de vectores
cat > /tmp/vector_add.cu << 'EOF'
#include <stdio.h>
__global__ void vectorAdd(float *a, float *b, float *c, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    if (i < n) c[i] = a[i] + b[i];
}
int main() {
    printf("CUDA funcionando correctamente\n");
    return 0;
}
EOF

nvcc -o /tmp/vector_add /tmp/vector_add.cu && /tmp/vector_add

Solución de Problemas

nvcc no se encuentra tras la instalación

# Verificar que el PATH incluye el directorio de CUDA
echo $PATH | grep cuda

# Añadir manualmente si falta
export PATH=/usr/local/cuda/bin:$PATH

# Verificar dónde está instalado nvcc
find /usr/local -name "nvcc" 2>/dev/null

Error: CUDA driver version is insufficient for CUDA runtime version

El driver instalado es más antiguo que la versión de CUDA. Debes actualizar el driver o instalar una versión más antigua de CUDA.

# Ver la versión del driver
nvidia-smi | grep "Driver Version"

# Instalar una versión de CUDA compatible con el driver actual

TensorFlow/PyTorch no detecta la GPU

# Verificar que las bibliotecas de CUDA son encontradas por el linker
ldconfig -p | grep libcuda
ldconfig -p | grep libcudnn

# Verificar la variable LD_LIBRARY_PATH
echo $LD_LIBRARY_PATH

# Si falta, añadir
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
sudo ldconfig

Error de compilación: gcc version not supported

# CUDA puede requerir una versión específica de GCC
# Instalar la versión compatible
sudo apt-get install -y gcc-11 g++-11

# Usar esa versión con nvcc
nvcc --compiler-bindir /usr/bin/gcc-11 -o programa programa.cu

Conclusión

CUDA Toolkit correctamente instalado y configurado es la base para todo el ecosistema de computación GPU en Linux. Con cuDNN instalado y las variables de entorno configuradas, los frameworks de machine learning como TensorFlow y PyTorch detectarán la GPU automáticamente. La gestión de múltiples versiones con enlaces simbólicos garantiza la flexibilidad necesaria para trabajar con diferentes proyectos que requieren distintas versiones de CUDA.