本文へスキップ
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 コンパイラを見つけられません。

根本原因: 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 が必要)

  • PowerShell で WSL を更新: 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 を返す

これはディープラーニング開発者にとって最も苛立たしい問題の 1 つです。

診断の手順:

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 には Microsoft Visual Studio の C++ コンパイラ (cl.exe) が必要で、それは 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                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

解決策:

ステップ 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 をインストールするときは、Custom Installation を使い、以下の選択を解除:

  • GeForce Experience (すでにインストールされている場合)

  • Display Driver (すでに動くドライバーを持っている場合)

インストールするのは:

  • 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 からダウンロードする

    • チェックサムを検証する

    • あなたの OS の公式インストールガイドに従う

インストール中:

  1. 正しい順序でインストールする

    • 最初にドライバー (または CUDA インストーラに任せる)

    • 2 番目に CUDA ツールキット

    • 3 番目に cuDNN

    • 最後にフレームワーク (PyTorch/TensorFlow)

  2. 安定のためにローカルインストーラを使う

    • ネットワークインストーラは失敗したり、間違ったバージョンを引き込んだりする

    • ローカルの runfile はより多くの制御を与える

  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 月