【NVIDIA】CUDAバージョン管理ベストプラクティス（複数バージョン共存ガイド）

はじめに

深層学習や科学技術計算の開発環境を構築する際、プロジェクトやフレームワークごとに要求されるCUDAバージョンが異なることに頭を悩ませた経験はありませんか？例えば、ある研究プロジェクトではPyTorch 2.0を使用するためにCUDA 11.7が必要な一方、別のプロダクション環境では古いコードベースがCUDA 10.2に依存している、といった状況はよくあります。単一のCUDAバージョンしかインストールできない環境では、このような要求の衝突が開発の大きな障害となります。

本記事では、NVIDIA GPUを搭載したLinuxシステム（Ubuntuを主な例とします）において、複数のCUDA Toolkitバージョンを安全にインストールし、柔軟に切り替えて使用するためのベストプラクティスを詳細に解説します。システム全体のデフォルトを壊すことなく、ユーザーセッションやプロジェクトごとに適切なCUDA環境を構築する方法を、具体的な手順と共に紹介します。

前提条件・必要な環境

以下の環境を前提とします。異なるディストリビューションでも概念は同じですが、パッケージマネージャやパスの扱いが若干異なる場合があります。

• OS: Ubuntu 20.04 LTS または 22.04 LTS（他のディストリビューションでも応用可能）
• シェル: Bash（デフォルトシェルを想定）
• 権限: パッケージのインストールにはsudo権限が必要です。環境変数の設定などは一般ユーザーで行います。
• NVIDIAドライバ: インストール済みのNVIDIAドライバは、使用したい全てのCUDAバージョンに対応しているものを選択してください。通常、新しいドライバは過去の複数のCUDAバージョンをサポートします。最新のドライバをインストールしておくことが無難です。

重要: 公式のnvidia-cuda-toolkitパッケージ（apt install nvidia-cuda-toolkit）はシステム全体に単一バージョンをインストールするため、本記事で紹介する共存方法には使用しません。

手順1： NVIDIA公式リポジトリの設定とCUDA Toolkitのインストール

まず、NVIDIAの公式リポジトリを追加し、複数バージョンのCUDA Toolkitを並列インストールできるようにします。

1. リポジトリキーとパッケージリストを追加します。

   # キーの追加
   wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
   sudo dpkg -i cuda-keyring_1.1-1_all.deb
   sudo apt update

   （注: URLのubuntu2204は、ご使用のUbuntuバージョンに合わせて変更してください。例: ubuntu2004）

2. 特定のCUDAバージョンをインストールします。例えば、CUDA 11.8とCUDA 12.1を共存させたい場合：

   # CUDA 11.8 のインストール
   sudo apt install cuda-toolkit-11-8
   
   # CUDA 12.1 のインストール
   sudo apt install cuda-toolkit-12-1

   これらは/usr/local/cuda-11.8、/usr/local/cuda-12.1という異なるディレクトリにインストールされます。従来のシンボリックリンク/usr/local/cudaは、最後にインストールしたバージョンを指すかもしれませんが、このリンクに依存せず、明示的なパス指定で管理することが共存の鍵です。

手順2： 環境変数によるCUDAバージョンの切り替え

システム全体の設定を変更せずに、シェルセッションやプロジェクトごとに使用するCUDAバージョンを切り替える最も一般的な方法は、環境変数PATHとLD_LIBRARY_PATHを設定することです。

1. ユーザーのホームディレクトリに設定用のスクリプトを作成します。例：~/.cuda_envs.sh

   #!/bin/bash
   
   # CUDA 11.8 を有効化する関数
   enable_cuda118() {
       export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}
       export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
       export CUDA_HOME=/usr/local/cuda-11.8
       echo "CUDA 11.8 environment activated."
   }
   
   # CUDA 12.1 を有効化する関数
   enable_cuda121() {
       export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}}
       export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
       export CUDA_HOME=/usr/local/cuda-12.1
       echo "CUDA 12.1 environment activated."
   }
   
   # 現在の設定を表示する関数
   show_cuda_env() {
       echo "CUDA_HOME: ${CUDA_HOME:-Not set}"
       which nvcc 2>/dev/null && nvcc --version | grep "release"
   }

2. ~/.bashrcに以下の行を追加し、シェル起動時にスクリプトを読み込むようにします。

   # CUDA環境切り替えユーティリティを読み込み
   source ~/.cuda_envs.sh

3. 新しいターミナルを開くか、source ~/.bashrcを実行します。これで、ターミナル上でenable_cuda118やenable_cuda121と入力するだけで、そのセッション内で使用するCUDAバージョンを切り替えられます。show_cuda_envで現在の設定を確認できます。

注意点: LD_LIBRARY_PATHの設定は強力ですが、他のライブラリと競合を起こす可能性もあります。プロジェクト固有の環境構築には、次の手順で紹介するDockerの利用がより堅牢です。

手順3： PyTorch/TensorFlowとの互換性管理

深層学習フレームワークは、特定のCUDAバージョンとcuDNNバージョンに強く依存します。以下は主要フレームワークの対応表の例です（最新情報は必ず公式ドキュメントで確認してください）。

PyTorchをインストールする際は、環境変数で切り替えたCUDAバージョンに合ったwheelをpipでインストールします。

# CUDA 11.8環境でPyTorch 2.0をインストール
enable_cuda118
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1環境でPyTorch 2.1をインストール
enable_cuda121
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

異なるCUDAバージョン用のPyTorchを同じPython環境に混在させることは避け、venvやcondaで仮想環境を分離することを強く推奨します。

# 仮想環境ごとにフレームワークをインストール
# プロジェクトA (CUDA 11.8)
python -m venv projectA_venv
source projectA_venv/bin/activate
enable_cuda118
pip install torch...cu118

# プロジェクトB (CUDA 12.1)
python -m venv projectB_venv
source projectB_venv/bin/activate
enable_cuda121
pip install torch...cu121

手順4： Dockerによる完全な環境分離

最もクリーンで再現性の高い方法は、Dockerコンテナを使用することです。NVIDIAは各CUDAバージョン用の公式Dockerイメージを提供しています。

1. NVIDIA Container Toolkitをインストールします。

   # リポジトリの設定とインストール
   distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
   curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
   curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
     sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
     sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   sudo apt update
   sudo apt install -y nvidia-container-toolkit
   sudo systemctl restart docker

2. プロジェクトごとにDockerfileを作成し、ベースイメージでCUDAバージョンを固定します。

   # Dockerfile for CUDA 11.8 + PyTorch
   FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04
   
   RUN apt update && apt install -y python3-pip
   RUN pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   
   WORKDIR /workspace
   COPY . .

   # Dockerfile for CUDA 12.1 + PyTorch
   FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04
   
   RUN apt update && apt install -y python3-pip
   RUN pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
   
   WORKDIR /workspace
   COPY . .

3. コンテナをビルド・実行します。ホストのCUDAバージョンに関係なく、コンテナ内で指定したバージョンが使用されます。

   # ビルド
   docker build -t myproject:cuda118 -f Dockerfile.cuda118 .
   
   # 実行 (GPUアクセス付き)
   docker run --gpus all -it --rm myproject:cuda118 python3 -c "import torch; print(torch.cuda.is_available())"

トラブルシューティング

• 問題: nvcc --versionとnvidia-smiで表示されるCUDAバージョンが異なる。

  原因と解決: これは正常です。nvidia-smiはGPUドライバがサポートする最高のCUDAバージョンを表示します。一方、nvcc --versionは実際にインストールされ、現在の環境変数で指定されているCUDA Toolkitのバージョンを表示します。開発時に参照すべきはnvccのバージョンです。

• 問題: PyTorchがCUDAを認識しない (torch.cuda.is_available()がFalseを返す)。

  原因と解決:
  1. PyTorchのインストール時に指定したCUDAバージョンと、現在の環境変数CUDA_HOME/PATHが指すCUDAバージョンが一致しているか確認。enable_cudaXXXを実行した後、仮想環境を有効化したか確認。
  2. 仮想環境内で再度PyTorchをインストールしてみる。
  3. Dockerを使用している場合、--gpus allオプションを忘れていないか確認。

• 問題: ライブラリのリンクエラー (libcudart.so.XX: cannot open shared object file)。

  原因と解決: LD_LIBRARY_PATHが正しく設定されていないか、別のバージョンのライブラリが優先されて参照されています。echo $LD_LIBRARY_PATHでパスを確認し、必要なCUDAのlib64ディレクトリが含まれているか確認してください。Docker環境では、ベースイメージのCUDAバージョンが合っているか確認します。

• 問題: システムのパッケージ更新後にCUDA関連のエラーが発生。

  原因と解決: システムの/usr/local/cudaシンボリックリンクが更新パッケージによって意図せず書き換えられた可能性があります。本記事の方法ではこのリンクに依存しないため、環境変数CUDA_HOMEを明示的に設定しているか確認し、必要に応じて~/.cuda_envs.shの設定を再度ソースしてください。

まとめ

複数のCUDAバージョンを1台のマシンで共存・管理するには、システム全体のデフォルトに依存するのではなく、環境変数による明示的な制御が基本となります。開発セッション単位での切り替えにはシェルの環境変数設定が、プロジェクト単位での完全な再現性確保にはDockerコンテナの利用が最も強力で推奨される方法です。PyTorchやTensorFlowなどのフレームワークは、仮想環境と組み合わせて各CUDAバージョン用に分離してインストールします。

このプラクティスを身につけることで、異なるCUDA要件を持つ複数のプロジェクトを並行してスムーズに進められ、バージョン依存による環境構築のストレスから解放されるでしょう。常に公式ドキュメントでフレームワークとCUDAの対応関係を確認し、適切なバージョンの組み合わせを選択することが、トラブルを未然に防ぐコツです。