問題の概要：CUDAバージョン不一致によるエラー
AI開発、特に深層学習のモデルトレーニングや推論を行う際、異なるフレームワークやプロジェクトが要求するCUDAバージョンが異なることがよくあります。例えば、あるプロジェクトではPyTorch 1.x系を使うためにCUDA 10.2が必要で、別のプロジェクトでは最新の機能を使うためにCUDA 11.7が必要といった状況です。このような場合、単一のCUDAバージョンしかインストールされていないと、以下のような典型的なエラーが発生します。
ImportError: libcudart.so.11.0: cannot open shared object file: No such file or directory
または、nvcc --version と nvidia-smi で表示されるCUDAバージョンが異なり、混乱を招くこともあります。
$ nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2021 NVIDIA Corporation
Built on Thu_Nov_18_09:45:30_PST_2021
Cuda compilation tools, release 11.5, V11.5.119
$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 470.161.03 Driver Version: 470.161.03 CUDA Version: 11.4 |
|-------------------------------+----------------------+----------------------+
これらのエラーや不一致は、システムのデフォルトCUDAバージョンと、アプリケーションが求めるバージョンが合っていないことが原因です。CUDAツールキットをアンインストールして再インストールするのは非現実的です。ここでは、Debian/Ubuntu系のLinuxディストリビューションで広く使われる update-alternatives ユーティリティを活用した、スマートな共存管理方法を紹介します。
原因の解説：シンボリックリンクとパスの問題
CUDAツールキットは、/usr/local/cuda というシンボリックリンクを介してシステムのデフォルトバージョンを指し示すように設計されています。このリンクが指す先が、実際にインストールされている特定のバージョン（例: /usr/local/cuda-11.5, /usr/local/cuda-10.2）になります。
問題は、この /usr/local/cuda リンクを手動で変更したり、異なる方法で複数バージョンをインストールしたりすると、管理が煩雑になり、リンクの参照先がぶれてしまうことです。その結果、コンパイラ(nvcc)やライブラリ(libcudart.so)を探すパスが正しく設定されず、前述の「shared object file not found」エラーが発生します。
update-alternatives は、このシステム全体のデフォルトシンボリックリンクを一元的に管理するためのツールです。複数の候補（今回は異なるCUDAバージョンのパス）を登録しておき、優先度に基づいて簡単に切り替えることができます。これにより、プロジェクトやユーザーごとに一貫したCUDA環境を提供できるのです。
解決方法：update-alternativesを使ったステップバイステップ管理
ここでは、CUDA 11.5とCUDA 10.2が既に /usr/local/cuda-11.5 と /usr/local/cuda-10.2 にインストールされていることを前提に説明します。
ステップ1: update-alternativesグループの作成と候補の登録
まず、管理対象となるシンボリックリンク「cuda」のためのグループを作成し、各CUDAバージョンを候補として登録します。--install オプションでは、リンクのパス、グループ名、実際のバイナリ/ディレクトリのパス、優先度を指定します。優先度は数値が高い方が自動選択時に優先されます。
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-11.5 115
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-10.2 102
ステップ2: 現在の設定確認と手動切り替え
登録された候補を一覧表示して、現在どのバージョンが選択されているかを確認します。
sudo update-alternatives --config cuda
このコマンドを実行すると、以下のような対話型メニューが表示されます。
There are 2 choices for the alternative cuda (providing /usr/local/cuda).
Selection Path Priority Status
------------------------------------------------------------
* 0 /usr/local/cuda-11.5 115 auto mode
1 /usr/local/cuda-10.2 102 manual mode
2 /usr/local/cuda-11.5 115 manual mode
Press <enter> to keep the current choice[*], or type selection number:
ここで、切り替えたいバージョンの番号（例：CUDA 10.2に切り替えるなら「1」）を入力し、Enterキーを押します。
ステップ3: 切り替えの確認
切り替えが正しく行われたか、nvcc --version と /usr/local/cuda リンクの指す先を確認します。
nvcc --version
ls -l /usr/local/cuda
出力例：
$ ls -l /usr/local/cuda
lrwxrwxrwx 1 root root 22 Aug 10 15:30 /usr/local/cuda -> /etc/alternatives/cuda
$ ls -l /etc/alternatives/cuda
lrwxrwxrwx 1 root root 25 Aug 10 15:30 /etc/alternatives/cuda -> /usr/local/cuda-10.2
# nvccのバージョンも10.2を示すようになります。
ステップ4: 環境変数PATHとLD_LIBRARY_PATHの設定（重要）
update-alternatives でシンボリックリンクを切り替えても、シェルの環境変数が古いパスを参照したままではエラーが発生する可能性があります。特に LD_LIBRARY_PATH は共有ライブラリを探すパスなので、必須です。.bashrc または .zshrc に以下の設定を追加しましょう。
export PATH=/usr/local/cuda/bin:${PATH}
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:${LD_LIBRARY_PATH}
設定を反映させます。
source ~/.bashrc # または source ~/.zshrc
これで、ターミナルを新しく開くたびに、現在選択されている /usr/local/cuda リンクに基づいた正しいバージョンのバイナリとライブラリが使用されます。
コード例・コマンド例：よく使う操作一覧
候補の追加（新しいCUDAバージョンをインストールした後）
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-12.1 121
候補の削除（アンインストールしたCUDAバージョンをリストから外す）
sudo update-alternatives --remove cuda /usr/local/cuda-10.1
現在の選択を確認（非対話型）
update-alternatives --query cuda
自動モードに戻す
最高優先度の候補が自動的に選択されます。
sudo update-alternatives --auto cuda
まとめ・補足情報
update-alternatives を使ったCUDAバージョン管理は、システム全体のデフォルトをクリーンに保ちながら、必要に応じて柔軟に切り替えるための強力な方法です。これにより、プロジェクトごとの要件の違いに悩まされることなく、開発を進めることができます。
重要な補足点：
- ドライバーバージョン:
nvidia-smiに表示される「CUDA Version」は、GPUドライバーがサポートする最高のCUDAランタイムバージョンです。実際にインストールされているCUDAツールキットのバージョン（nvcc --version）とは別物です。ドライバーは新しいものをインストールしておくことで、幅広いCUDAツールキットバージョンをサポートできます。 - 仮想環境との併用: PyTorchやTensorFlowをcondaやvenvなどの仮想環境内でインストールすると、仮想環境内に独立したCUDAライブラリがインストールされることがあります。その場合、仮想環境内では仮想環境に付属するライブラリが優先されるため、システムのデフォルトCUDAバージョンの影響を受けにくくなります。システム全体のベース環境を整える手段として、本記事の方法は有効です。
- 他のツールへの応用:
update-alternatives はgcc,python,javaなど、複数バージョンを管理したいあらゆるシステムツールに適用可能です。
この方法を習得すれば、「CUDAバージョン地獄」に陥ることなく、スムーズにAI開発環境を構築・維持できるようになるでしょう。