본문으로 건너뛰기
CUDA 설치 문제 해결 완전 가이드

CUDA 설치 문제 해결 완전 가이드

, 12분 소요, By Jaber Jaber

Research

CUDA 개발을 시작하며 짜증 나는 설치 문제를 만났을 것입니다. 나는 수백 건의 개발자 경험을 분석하여 가장 흔한 CUDA 설치 문제를 극복하도록 돕는 이 포괄적인 가이드를 엮었습니다.

모든 CUDA 개발자가 겪은 일입니다. 툴킷을 설치하고, 모든 것이 멀쩡해 보이고, 그다음 nvcc --version이 "command not found"를 반환합니다. 더 나쁜 경우, 내 기계에서는 모든 것이 되는데 다른 사람의 GPU에서는 깨집니다. 수십 팀이 이 문제들을 디버깅하도록 돕고 나서, 나는 같은 문제들이 반복해서 나오는 것을 보았습니다.

이 가이드는 모든 주요 CUDA 설치 문제와 그것을 고치는 정확한 방법을 다룹니다. 이제 시행착오는 없습니다.

목차

흔한 문제들:

  • PATH와 환경 변수 문제

  • 드라이버와 툴킷 버전 불일치

  • WSL2 고유의 문제

  • Secure Boot와 UEFI 문제

  • 깨진 패키지 의존성

  • cuDNN 설치와 호환성

  • PyTorch CUDA를 쓸 수 없음

  • Windows 고유의 문제

  • 불완전한 설치

예방을 위한 모범 사례


1. PATH와 환경 변수 문제

문제: nvcc --version이 "command not found"를 반환

설치 뒤 개발자가 마주하는 가장 흔한 문제입니다. 툴킷은 설치되었는데 시스템이 CUDA 컴파일러를 찾지 못합니다.

근본 원인: CUDA 바이너리가 시스템의 PATH 환경 변수에 없습니다.

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

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

Windows용 해결:

  1. 시스템 속성 열기 → 고급 → 환경 변수

  2. PATH에 추가: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin

  3. 새 변수 CUDA_PATH 만들기: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8

  4. 터미널이나 IDE 재시작

확인:

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

2. 드라이버와 툴킷 버전 불일치

문제: "CUDA driver version is insufficient" 또는 버전 불일치 오류

근본 원인: NVIDIA 드라이버가 설치한 CUDA 툴킷 버전을 지원하지 않거나, 서로 다른 CUDA 구성 요소 사이에 불일치가 있습니다.

CUDA 버전 이해하기:

  • nvidia-smi는 드라이버가 지원하는 최대 CUDA 버전을 보여줍니다

  • nvcc --version은 설치된 툴킷 버전을 보여줍니다

  • 둘은 다를 수 있고, 그것은 보통 괜찮습니다. 드라이버는 더 오래된 툴킷을 지원합니다

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

해결 1: 드라이버 업그레이드

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

해결 2: 호환되는 CUDA 버전 설치

드라이버를 업그레이드할 수 없다면, 드라이버 버전에 맞는 더 오래된 CUDA 툴킷을 설치하세요. CUDA 호환 매트릭스를 확인하세요.

해결 3: NVML 드라이버/라이브러리 불일치 고치기

이 오류는 드라이버 업데이트 뒤에 자주 나타납니다:

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. WSL2 고유의 문제

문제: Windows의 WSL2에서 CUDA가 작동하지 않음

WSL2는 네이티브 Linux 설치와 다른, CUDA 지원만의 요구 사항을 갖습니다.

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

WSL2의 결정적 규칙:

  1. WSL2 안에 NVIDIA 드라이버를 설치하지 마세요: Windows에서 옵니다

  2. WSL2에는 드라이버가 아니라 CUDA 툴킷만 설치하세요

  3. Windows에는 WSL2 호환 NVIDIA 드라이버가 있어야 합니다

해결:

1단계: 올바른 Windows 드라이버 설치 NVIDIA의 WSL 페이지에서 WSL용 CUDA 지원 드라이버를 내려받으세요.

2단계: WSL2가 GPU를 보는지 확인

Shell
# In WSL2 terminal
nvidia-smi

이것이 되면 Windows 드라이버가 올바르게 설정된 것입니다.

3단계: WSL2에 CUDA 툴킷 설치

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!

4단계: 환경 변수 설정

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

흔한 WSL2 문제들:

문제: "GPU not detected in WSL2"

  • Windows에 WSL2 지원 드라이버가 있는지 확인하세요

  • WSL 커널 버전 확인: wsl cat /proc/version (5.10.43.3 이상 필요)

  • WSL 업데이트: PowerShell에서 wsl --update

문제: 호환되지 않는 CUDA 버전

  • WSL2에서는 CUDA 11.0 이상만 쓰세요

  • 서로 다른 방법의 CUDA 설치를 섞지 마세요


4. Secure Boot와 UEFI 문제

문제: "Required key not available" 또는 Secure Boot 켜짐 상태에서 드라이버가 로드되지 않음

근본 원인: UEFI Secure Boot는 NVIDIA 드라이버를 포함해 서명되지 않은 커널 모듈의 로드를 막습니다.

해결 1: Secure Boot 끄기 (가장 쉬움)

  1. 재시작하고 BIOS/UEFI 진입 (보통 시작 중 DEL, F2 또는 F12)

  2. Security 또는 Boot 설정으로 이동

  3. Secure Boot 끄기

  4. 저장하고 나가기

  5. Linux로 재시작

해결 2: NVIDIA 모듈 서명 (Secure Boot 켜짐 유지)

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)

해결 3: 내장 DKMS 서명 쓰기 (Ubuntu 18.04 이상)

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

확인:

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. 깨진 패키지 의존성

문제: "Unable to correct problems, you have held broken packages" 또는 apt-get 실패

이것은 보통 CUDA 설치가 기존 패키지와 충돌하거나 이전 설치가 불완전할 때 일어납니다.

진단:

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

해결 1: 깨끗한 백지 접근

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

해결 2: 특정 의존성 충돌 고치기

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

해결 3: "File Already Exists" 충돌 다루기

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

계속되는 문제라면:

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. cuDNN 설치와 호환성

문제: cuDNN 버전 불일치 또는 "cannot find cuDNN"

근본 원인: 딥러닝 프레임워크는 CUDA 버전과 일치해야 하는 특정 cuDNN 버전을 요구합니다.

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

해결 1: apt로 호환되는 cuDNN 설치 (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

해결 2: 수동 설치

  1. NVIDIA의 cuDNN 페이지에서 cuDNN 내려받기 (무료 계정 필요)

  2. CUDA 툴킷에 맞는 버전 고르기

  3. 압축을 풀고 파일 복사:

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*

확인:

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

해결 3: Conda로 여러 cuDNN 버전 갖기

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

흔한 오류: "Loaded runtime CuDNN library X but source was compiled with Y"

이것은 Python 패키지가 다른 cuDNN 버전을 기대한다는 뜻입니다.

고치기:

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를 쓸 수 없음

문제: torch.cuda.is_available()가 False 반환

딥러닝 개발자에게 가장 짜증 나는 문제 중 하나입니다.

진단 단계:

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

흔한 원인과 해결:

원인 1: CPU 전용 PyTorch 설치

가장 흔한 문제입니다. 기본 pip install torch는 CPU 전용 버전을 설치합니다.

해결:

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

원인 2: PyTorch CUDA 버전이 드라이버와 맞지 않음

PyTorch는 자신의 CUDA 런타임을 묶어 오지만, 드라이버가 그것을 지원해야 합니다.

해결:

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

원인 3: 잘못된 컴퓨트 능력

오래된 GPU는 최신 PyTorch 빌드가 지원하지 않을 수 있습니다.

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())"

해결:

  • 컴퓨트 능력 3.5 미만: 최신 PyTorch가 지원하지 않습니다

  • 컴퓨트 능력 3.5~5.2: 더 오래된 PyTorch 버전이 필요할 수 있습니다

  • 컴퓨트 능력 5.0 이상: 완전히 지원됩니다

GPU가 너무 오래되었다면 이것을 고려하세요:

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

원인 4: 환경/Conda 문제

해결:

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

원인 5: CUDA_VISIBLE_DEVICES가 잘못 설정됨

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

빠른 문제 해결 스크립트:

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. Windows 고유의 문제

문제: "Cannot find compiler 'cl.exe' in PATH"

근본 원인: Windows의 CUDA는 CUDA 툴킷에 포함되지 않은 Microsoft Visual Studio의 C++ 컴파일러(cl.exe)를 요구합니다.

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

해결:

1단계: Visual Studio 설치

  1. Visual Studio Community 내려받기 (무료)

  2. 설치 중 "Desktop development with C++" 선택

  3. 이 구성 요소들이 선택되어 있는지 확인:

    • MSVC v143 C++ 빌드 도구 (또는 최신)

    • Windows SDK

    • C++ CMake 도구

2단계: 설치 확인

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

3단계: 필요하면 PATH에 추가

cl.exe가 일반 명령 프롬프트에서 발견되지 않으면:

  1. cl.exe 위치 찾기 (보통):

    Text
    C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.XX.XXXXX\bin\Hostx64\x64
  2. 시스템 PATH에 추가하거나 Visual Studio의 Developer Command Prompt 사용

4단계: CUDA가 컴파일러를 찾는지 확인

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

흔한 VS 버전 호환 문제:

VS 2022 17.10 이상과 CUDA 12.4 이하가 있다면:

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

문제: GeForce Experience 충돌 (Windows)

해결:

Windows에 CUDA를 설치할 때 사용자 지정 설치를 쓰고 선택 해제하세요:

  • GeForce Experience (이미 설치되어 있다면)

  • 디스플레이 드라이버 (이미 작동하는 드라이버가 있다면)

이것만 설치하세요:

  • CUDA 툴킷

  • 개발 도구

  • 문서


9. 불완전한 설치

문제: "Incomplete installation" 또는 "Driver not selected" 경고

증상:

  • 설치는 끝나지만 경고가 있음

  • nvidia-smi는 되는데 nvcc는 안 됨

  • 일부 CUDA 샘플이 컴파일에 실패함

해결 1: 툴킷만 설치 (드라이버가 이미 작동할 때)

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

해결 2: 완전 재설치

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

해결 3: 빠진 구성 요소 고치기

특정 구성 요소만 빠졌다면:

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. 모범 사례

예방이 치료보다 낫다

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

설치 전:

  1. 호환성 확인

    • GPU 컴퓨트 능력

    • OS 버전과 커널

    • 드라이버 요구 사항

    • 프레임워크 요구 사항 (PyTorch/TensorFlow 버전)

  2. 기존 설치 정리

    Shell
    sudo apt-get remove --purge '^nvidia-.*' '^cuda-.*'
    sudo apt-get autoremove
  3. 공식 출처 쓰기

    • nvidia.com에서 내려받으세요, 제3자 저장소가 아니라

    • 체크섬 확인

    • OS의 공식 설치 가이드를 따르세요

설치 중:

  1. 올바른 순서로 설치

    • 드라이버 먼저 (또는 CUDA 설치 프로그램에 맡기기)

    • CUDA 툴킷 둘째

    • cuDNN 셋째

    • 프레임워크 (PyTorch/TensorFlow) 마지막

  2. 안정성을 위해 로컬 설치 프로그램 쓰기

    • 네트워크 설치 프로그램은 실패하거나 잘못된 버전을 끌어올 수 있습니다

    • 로컬 런파일이 더 많은 통제를 줍니다

  3. 버전 기록하기

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

설치 후:

  1. 모두 확인

    Shell
    # Driver
    nvidia-smi
    
    # Toolkit
    nvcc --version
    
    # Test compilation
    cd /usr/local/cuda/samples/1_Utilities/deviceQuery
    sudo make
    ./deviceQuery
  2. 환경 백업 만들기

    Shell
    # Save your working environment
    conda env export > working_cuda_env.yml
    
    # Or with pip
    pip freeze > requirements.txt
  3. 설정 문서화 기록해 두세요:

    • GPU 모델

    • 드라이버 버전

    • CUDA 버전

    • cuDNN 버전

    • 프레임워크 버전

    • OS와 커널 버전

권장 설치 경로:

초보자용:

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

고급 사용자용:

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

딥러닝용:

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

문제가 생겼을 때:

  1. 당황 설치 하지 마세요

    • 여러 버전을 설치해도 문제가 고쳐지지 않습니다

    • 먼저 정리하고, 그다음 재설치하세요

  2. 오류 메시지를 주의 깊게 읽으세요

    • 대부분의 오류는 무엇이 잘못됐는지 정확히 말합니다

    • 그 구체적인 오류 메시지를 검색하세요

  3. 로그 확인

    Shell
    # CUDA installer logs
    cat /var/log/cuda-installer.log
    
    # System logs
    dmesg | grep -i nvidia
    journalctl -xe | grep -i nvidia
  4. 올바르게 도움 요청 포럼에 글을 올릴 때 포함하세요:

    • OS와 버전

    • GPU 모델

    • nvidia-smi 출력

    • nvcc --version 출력

    • 완전한 오류 메시지

    • 이미 시도한 것


빠른 문제 해결 체크리스트

CUDA가 작동하지 않을 때 이 체크리스트를 쓰세요:

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

결론

CUDA 설치는 까다로울 수 있지만, 대부분의 문제는 이 흔한 범주에 속합니다. 핵심은:

  1. 오류 메시지로 구체적인 문제 파악

  2. 버전 불일치, 빠진 의존성 등의 근본 원인 이해

  3. 모두 다시 설치하는 대신 맞춤 해결 적용

  4. 제대로 시험해 고침 확인

기억하세요. 작동하는 CUDA 설치에는 이것이 필요합니다:

  • 호환되는 GPU 하드웨어

  • 올바른 NVIDIA 드라이버

  • CUDA 툴킷

  • 올바른 환경 변수

  • (딥러닝이라면) 호환되는 cuDNN

  • (딥러닝이라면) CUDA 지원으로 설치된 프레임워크

이 해결들을 시도한 뒤에도 막혔다면 NVIDIA Developer Forums와 Stack Overflow의 CUDA 커뮤니티가 훌륭한 자원입니다.


마지막 업데이트: 2025년 10월