Pular para o conteúdo
O guia completo para corrigir problemas de instalação do CUDA

O guia completo para corrigir problemas de instalação do CUDA

, 12 min de leitura, By Jaber Jaber

Research

Se você está começando com desenvolvimento em CUDA, provavelmente já encontrou problemas frustrantes de instalação. Analisei centenas de experiências de desenvolvedores e reuni este guia completo para ajudá-lo a superar os desafios mais comuns de instalação do CUDA.

Todo desenvolvedor de CUDA já esteve lá: você instala o toolkit, tudo parece bem, e então nvcc --version devolve "command not found". Ou pior: tudo funciona na sua máquina mas quebra na GPU de outra pessoa. Depois de ajudar dezenas de times a depurar esses problemas, vi os mesmos falhos repetidamente.

Este guia cobre todos os principais problemas de instalação do CUDA e como corrigi-los exatamente. Chega de tentativa e erro.

Sumário

Problemas comuns:

  • Problemas de PATH e variáveis de ambiente

  • Divergências de versão entre driver e toolkit

  • Problemas específicos do WSL2

  • Problemas de Secure Boot e UEFI

  • Dependências de pacotes quebradas

  • Instalação e compatibilidade do cuDNN

  • PyTorch CUDA Not Available

  • Problemas específicos do Windows

  • Instalações incompletas

Boas práticas para prevenir


1. Problemas de PATH e variáveis de ambiente

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

Este é o problema mais comum depois de instalar o CUDA. O toolkit está instalado, mas o sistema não encontra o compilador do CUDA.

Causa raiz: os binários do CUDA não estão na variável de ambiente PATH do seu 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                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solução 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

Solução para Windows:

  1. Abra Propriedades do sistema → Avançado → Variáveis de ambiente

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

  3. Crie a nova variável CUDA_PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8

  4. Reinicie seu terminal ou IDE

Verificação:

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

2. Divergências de versão entre driver e toolkit

Problema: "CUDA driver version is insufficient" ou erros de versão incompatível

Causa raiz: seu driver NVIDIA não suporta a versão do toolkit CUDA que você instalou, ou há divergência entre os componentes do CUDA.

Entendendo as versões do CUDA:

  • nvidia-smi mostra a versão máxima de CUDA que seu driver suporta

  • nvcc --version mostra a versão do toolkit instalada

  • Elas podem ser diferentes, e isso normalmente está bem (o driver suporta toolkits mais antigos)

┌──────────────────────────────────────────────────────────────┐
│  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                  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solução 1: atualize seu 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

Solução 2: instale uma versão compatível do CUDA

Se você não pode atualizar o driver, instale um toolkit CUDA mais antigo que corresponda à versão do seu driver. Consulte a matriz de compatibilidade do CUDA.

Solução 3: corrija a divergência NVML entre driver e biblioteca

Este erro costuma aparecer depois de atualizar o 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 do WSL2

Problema: CUDA não funciona no WSL2 no Windows

O WSL2 tem requisitos próprios para o suporte a CUDA que diferem das instalações 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                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Regras críticas para WSL2:

  1. NÃO instale drivers NVIDIA dentro do WSL2: eles vêm do Windows

  2. Instale apenas o CUDA Toolkit no WSL2, não o driver

  3. O Windows precisa do driver NVIDIA compatível com WSL2

Solução:

Passo 1: instale o driver correto do Windows Baixe o driver com CUDA para WSL na página WSL da NVIDIA.

Passo 2: verifique que o WSL2 vê a GPU

Shell
# In WSL2 terminal
nvidia-smi

Se isso funciona, o driver do Windows está configurado corretamente.

Passo 3: instale o CUDA Toolkit no 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!

Passo 4: defina as variáveis de ambiente

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 comuns do WSL2:

Problema: "GPU not detected in WSL2"

  • Certifique-se de que o Windows tem o driver habilitado para WSL2

  • Confira a versão do kernel do WSL: wsl cat /proc/version (precisa de ≥ 5.10.43.3)

  • Atualize o WSL: wsl --update no PowerShell

Problema: versões de CUDA incompatíveis

  • Use apenas CUDA 11.0 ou superior no WSL2

  • Não misture instalações de CUDA de métodos diferentes


4. Problemas de Secure Boot e UEFI

Problema: "Required key not available" ou drivers que não carregam com Secure Boot

Causa raiz: o Secure Boot da UEFI impede o carregamento de módulos de kernel não assinados, incluindo os drivers NVIDIA.

Solução 1: desative o Secure Boot (o mais fácil)

  1. Reinicie e entre na BIOS/UEFI (normalmente DEL, F2 ou F12 durante o boot)

  2. Vá aos ajustes de Segurança ou de Boot

  3. Desative o Secure Boot

  4. Salve e saia

  5. Reinicie no Linux

Solução 2: assine os módulos NVIDIA (mantenha o Secure Boot ligado)

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)

Solução 3: use a assinatura embutida do DKMS (Ubuntu 18.04 ou 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

Verificação:

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. Dependências de pacotes quebradas

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

Isso costuma acontecer quando instalações do CUDA conflitam com pacotes existentes ou instalações anteriores 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

Solução 1: começar do zero

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

Solução 2: corrija conflitos específicos de dependência

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

Solução 3: trate conflitos de "arquivo já existe"

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. Instalação e compatibilidade do cuDNN

Problema: versão de cuDNN incompatível ou "cannot find cuDNN"

Causa raiz: frameworks de aprendizado profundo exigem versões específicas de cuDNN que devem corresponder à sua versão do 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+                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solução 1: instale cuDNN compatível via 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

Solução 2: instalação manual

  1. Baixe o cuDNN na página de cuDNN da NVIDIA (requer conta gratuita)

  2. Escolha a versão que corresponde ao seu toolkit CUDA

  3. Extraia e copie os arquivos:

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*

Verificação:

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

Solução 3: várias versões de cuDNN com 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

Erro comum: "Loaded runtime CuDNN library X but source was compiled with Y"

Isso significa que seu pacote Python espera uma versão diferente de cuDNN.

Correção:

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() devolve False

Este é um dos problemas mais frustrantes para desenvolvedores de aprendizado profundo.

Passos 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 comuns e soluções:

Causa 1: você instalou o PyTorch só para CPU

Este é o problema mais comum. O pip install torch padrão instala a versão só para CPU.

Solução:

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: a versão de CUDA do PyTorch não corresponde ao driver

O PyTorch traz seu próprio runtime CUDA, mas seu driver precisa suportá-lo.

Solução:

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 errada

GPUs mais antigas podem não ser suportadas por versões recentes do PyTorch.

Confira a compute capability da 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())"

Solução:

  • Compute capability menor que 3.5: sem suporte do PyTorch moderno

  • Compute capability 3.5 a 5.2: pode precisar de versões mais antigas do PyTorch

  • Compute capability 5.0 ou superior: totalmente suportada

Se sua GPU é velha demais, considere:

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 ambiente ou Conda

Solução:

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 definida incorretamente

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

Roteiro 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 do Windows

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

Causa raiz: o CUDA no Windows exige o compilador C++ do Microsoft Visual Studio (cl.exe), que não vem no toolkit 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                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Solução:

Passo 1: instale o Visual Studio

  1. Baixe o Visual Studio Community (grátis)

  2. Durante a instalação, escolha "Desenvolvimento para desktop com C++"

  3. Certifique-se de que estes componentes estão marcados:

    • Ferramentas de build do C++ MSVC v143 (ou a mais recente)

    • Windows SDK

    • Ferramentas de CMake para C++

Passo 2: verifique a instalação

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

Passo 3: adicione ao PATH (se precisar)

Se cl.exe não é encontrado no Prompt de Comando normal:

  1. Ache a localização do cl.exe (normalmente):

    Text
    C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.XX.XXXXX\bin\Hostx64\x64
  2. Adicione ao PATH do sistema ou use o Prompt de Comando para Desenvolvedores do Visual Studio

Passo 4: verifique que o CUDA encontra o compilador

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

Problemas comuns de compatibilidade com VS:

Se você tem VS 2022 17.10 ou superior com CUDA 12.4 ou 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: conflitos com o GeForce Experience (Windows)

Solução:

Ao instalar o CUDA no Windows, use Instalação Personalizada e desmarque:

  • GeForce Experience (se já estiver instalado)

  • Display Driver (se você já tem um driver funcionando)

Instale apenas:

  • CUDA Toolkit

  • Development tools

  • Documentation


9. Instalações incompletas

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

Sintomas:

  • A instalação termina mas com avisos

  • nvidia-smi funciona mas nvcc não

  • Algumas amostras de CUDA não compilam

Solução 1: instalação só do toolkit (quando o driver já 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

Solução 2: reinstalação 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

Solução 3: corrija os componentes que faltam

Se apenas componentes específicos faltam:

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. Boas práticas

Prevenir é melhor que remediar

┌──────────────────────────────────────────────────────────────┐
│  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. Confira a compatibilidade

    • Compute capability da GPU

    • Versão do sistema operacional e do kernel

    • Requisitos do driver

    • Requisitos do framework (versões de PyTorch/TensorFlow)

  2. Limpe as instalações existentes

    Shell
    sudo apt-get remove --purge '^nvidia-.*' '^cuda-.*'
    sudo apt-get autoremove
  3. Use fontes oficiais

    • Baixe do nvidia.com, não de repositórios de terceiros

    • Verifique as somas de verificação

    • Siga o guia oficial de instalação para o seu sistema

Durante a instalação:

  1. Instale na ordem certa

    • Primeiro o driver (ou deixe o instalador do CUDA cuidar)

    • Segundo o CUDA Toolkit

    • Terceiro o cuDNN

    • Por último o framework (PyTorch/TensorFlow)

  2. Use instaladores locais para estabilidade

    • Instaladores de rede podem falhar ou puxar versões erradas

    • Runfiles locais dão mais controle

  3. Anote suas versões

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

Depois da instalação:

  1. Verifique tudo

    Shell
    # Driver
    nvidia-smi
    
    # Toolkit
    nvcc --version
    
    # Test compilation
    cd /usr/local/cuda/samples/1_Utilities/deviceQuery
    sudo make
    ./deviceQuery
  2. Crie um backup do ambiente

    Shell
    # Save your working environment
    conda env export > working_cuda_env.yml
    
    # Or with pip
    pip freeze > requirements.txt
  3. Documente sua configuração Guarde um registro de:

    • Modelo da GPU

    • Versão do driver

    • Versão do CUDA

    • Versão do cuDNN

    • Versões do framework

    • Sistema operacional e versão do kernel

Caminhos de instalação recomendados:

Para iniciantes:

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 usuários avançados:

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 aprendizado 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

Quando algo der errado:

  1. Não instale em pânico

    • Instalar várias versões não conserta os problemas

    • Limpe primeiro, depois reinstale

  2. Leia as mensagens de erro com atenção

    • A maioria dos erros diz exatamente o que está errado

    • Pesquise a mensagem de erro específica no Google

  3. Confira os logs

    Shell
    # CUDA installer logs
    cat /var/log/cuda-installer.log
    
    # System logs
    dmesg | grep -i nvidia
    journalctl -xe | grep -i nvidia
  4. Peça ajuda direito Ao publicar em fóruns, inclua:

    • Sistema operacional e versão

    • Modelo da GPU

    • A saída de nvidia-smi

    • A saída de nvcc --version

    • As mensagens de erro completas

    • O que você já tentou


Lista rápida de diagnóstico

Use esta lista quando o CUDA não 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                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Conclusão

A instalação do CUDA pode ser complicada, mas a maioria dos problemas cai nessas categorias comuns. A chave é:

  1. Identificar o problema específico com as mensagens de erro

  2. Entender a causa raiz (divergência de versão, dependências faltando, etc.)

  3. Aplicar a solução dirigida em vez de reinstalar tudo

  4. Verificar a correção com testes adequados

Lembre-se: uma instalação de CUDA funcionando exige:

  • Hardware de GPU compatível

  • Driver NVIDIA adequado

  • CUDA Toolkit

  • Variáveis de ambiente corretas

  • (Para aprendizado profundo) cuDNN compatível

  • (Para aprendizado profundo) Framework instalado com suporte CUDA

Se você ainda estiver travado depois de tentar estas soluções, a comunidade CUDA nos fóruns de desenvolvedores da NVIDIA e o Stack Overflow são recursos excelentes.


Última atualização: outubro de 2025