
O guia completo para corrigir problemas de instalação do CUDA
, 12 min de leitura, By Jaber Jaber
ResearchSe 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:
Solução para Windows:
Abra Propriedades do sistema → Avançado → Variáveis de ambiente
Adicione ao PATH:
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\binCrie a nova variável
CUDA_PATH:C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8Reinicie seu terminal ou IDE
Verificação:
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-smimostra a versão máxima de CUDA que seu driver suportanvcc --versionmostra a versão do toolkit instaladaElas 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
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:
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:
NÃO instale drivers NVIDIA dentro do WSL2: eles vêm do Windows
Instale apenas o CUDA Toolkit no WSL2, não o driver
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
Se isso funciona, o driver do Windows está configurado corretamente.
Passo 3: instale o CUDA Toolkit no WSL2
Passo 4: defina as variáveis de ambiente
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 --updateno 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)
Reinicie e entre na BIOS/UEFI (normalmente DEL, F2 ou F12 durante o boot)
Vá aos ajustes de Segurança ou de Boot
Desative o Secure Boot
Salve e saia
Reinicie no Linux
Solução 2: assine os módulos NVIDIA (mantenha o Secure Boot ligado)
Solução 3: use a assinatura embutida do DKMS (Ubuntu 18.04 ou superior)
Verificação:
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:
Solução 1: começar do zero
Solução 2: corrija conflitos específicos de dependência
Solução 3: trate conflitos de "arquivo já existe"
Para problemas persistentes:
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)
Solução 2: instalação manual
Baixe o cuDNN na página de cuDNN da NVIDIA (requer conta gratuita)
Escolha a versão que corresponde ao seu toolkit CUDA
Extraia e copie os arquivos:
Verificação:
Solução 3: várias versões de cuDNN com Conda
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:
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:
┌──────────────────────────────────────────────────────────────┐ │ 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:
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:
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:
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:
Causa 4: problemas de ambiente ou Conda
Solução:
Causa 5: CUDA_VISIBLE_DEVICES definida incorretamente
Roteiro rápido de diagnóstico:
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
Baixe o Visual Studio Community (grátis)
Durante a instalação, escolha "Desenvolvimento para desktop com C++"
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
Passo 3: adicione ao PATH (se precisar)
Se cl.exe não é encontrado no Prompt de Comando normal:
Ache a localização do cl.exe (normalmente):
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
Problemas comuns de compatibilidade com VS:
Se você tem VS 2022 17.10 ou superior com CUDA 12.4 ou anterior:
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-smifunciona masnvccnãoAlgumas amostras de CUDA não compilam
Solução 1: instalação só do toolkit (quando o driver já funciona)
Solução 2: reinstalação completa
Solução 3: corrija os componentes que faltam
Se apenas componentes específicos faltam:
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:
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)
Limpe as instalações existentes
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:
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)
Use instaladores locais para estabilidade
Instaladores de rede podem falhar ou puxar versões erradas
Runfiles locais dão mais controle
Anote suas versões
Depois da instalação:
Verifique tudo
Crie um backup do ambiente
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:
Para usuários avançados:
Para aprendizado profundo:
Quando algo der errado:
Não instale em pânico
Instalar várias versões não conserta os problemas
Limpe primeiro, depois reinstale
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
Confira os logs
Peça ajuda direito Ao publicar em fóruns, inclua:
Sistema operacional e versão
Modelo da GPU
A saída de
nvidia-smiA saída de
nvcc --versionAs 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 é:
Identificar o problema específico com as mensagens de erro
Entender a causa raiz (divergência de versão, dependências faltando, etc.)
Aplicar a solução dirigida em vez de reinstalar tudo
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