問題の概要：CUDAバージョン競合によるエラー
AI開発、特に深層学習のモデルトレーニングや推論を行う際、異なるフレームワークやライブラリが特定のCUDAバージョンに依存していることがあります。例えば、TensorFlow 2.10はCUDA 11.2を、PyTorchの最新版はCUDA 11.7または12.1を要求するなど、プロジェクトごとに必要なCUDAバージョンが異なるケースは珍しくありません。このような状況で、システムに一つのCUDAバージョンしかインストールされていないと、以下のようなエラーに頻繁に遭遇します。
ImportError: libcudart.so.11.0: cannot open shared object file: No such file or directory
あるいは、nvcc --versionで確認できるコンパイラバージョンと、Pythonからtorch.cuda.is_available()で参照されるランタイムバージョンが一致せず、思わぬ挙動を示すこともあります。システムのデフォルトCUDAを都度アンインストール/再インストールするのは非現実的であり、効率的な開発の大きな障壁となります。
原因の解説：シンボリックリンクとパスの管理
これらのエラーの根本原因は、CUDAツールキットの構成要素（nvccコンパイラ、libcudart.soなどのランタイムライブラリ）へのパスが、システム全体で一つのバージョンに「固定」されてしまっていることです。通常、CUDAをインストールすると、/usr/local/cuda というシンボリックリンクが作成され、これが使用するCUDAバージョン（例: /usr/local/cuda-11.8）を指します。アプリケーションやフレームワークはこの/usr/local/cudaを参照してライブラリを探します。
複数バージョンをインストールした場合、この/usr/local/cudaリンクを手動で書き換えることも可能ですが、ミスが発生しやすく、特にPATHやLD_LIBRARY_PATHといった環境変数との整合性を取るのが困難です。update-alternativesは、この「デフォルトとして使用するバージョン」をシステムレベルで統一的に管理するための強力なツールです。これにより、コマンドラインから簡単に、かつ安全にバージョン切り替えが可能になります。
解決方法：update-alternativesを使ったステップバイステップ管理
ここでは、CUDA 11.8とCUDA 12.1が既に/usr/local/cuda-11.8と/usr/local/cuda-12.1にインストールされていることを前提に説明します。
ステップ1：update-alternativesグループの登録
まず、管理対象となるコマンドやリンクをupdate-alternativesの「代替グループ」に登録します。主要な項目としてcuda（メインリンク）、nvcc（コンパイラ）を登録します。
# cuda（メインリンク）のグループを登録
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-11.8 100
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-12.1 200
# nvcc（コンパイラ）のグループを登録
sudo update-alternatives --install /usr/bin/nvcc nvcc /usr/local/cuda-11.8/bin/nvcc 100
sudo update-alternatives --install /usr/bin/nvcc nvcc /usr/local/cuda-12.1/bin/nvcc 200
コマンドの構成は--install [リンクパス] [グループ名] [実際のパス] [優先度]です。優先度は数値が高い方がデフォルト候補として選ばれやすくなります。ここではCUDA 12.1に高い優先度(200)を設定しています。
ステップ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-12.1 200 auto mode
1 /usr/local/cuda-11.8 100 manual mode
2 /usr/local/cuda-12.1 200 manual mode
Press <enter> to keep the current choice[*], or type selection number:
使用したいバージョンの番号（ここでは1または2）を入力し、Enterキーを押します。同様にnvccも切り替えます。
sudo update-alternatives --config nvcc
ステップ3：切り替えの確認
切り替えが正しく行われたか、以下のコマンドで確認します。
# メインリンクの確認
ls -l /usr/local/cuda
# 期待する出力: lrwxrwxrwx ... /usr/local/cuda -> /usr/local/cuda-11.8
# nvccバージョンの確認
nvcc --version
# 出力の最後の行でバージョンを確認。例: Cuda compilation tools, release 11.8, V11.8.89
# ランタイムライブラリパスの確認 (オプション)
echo $LD_LIBRARY_PATH
# /usr/local/cuda/lib64 が含まれていることを確認。含まれていない場合は下記のステップ4を実行。
ステップ4：環境変数の設定（~/.bashrcへの追記）
update-alternativesで切り替えた/usr/local/cudaリンクを確実に参照させるために、シェルの設定ファイルに環境変数を追加します。
# お使いのシェル設定ファイル（~/.bashrc または ~/.zshrc）を編集
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
# 変更を現在のシェルに反映
source ~/.bashrc
この設定により、ターミナルを起動するたびに、現在update-alternativesで選択されているCUDAバージョンのバイナリとライブラリが優先的に使用されるようになります。
コード例・コマンド例：よくある操作とトラブルシューティング
登録されている代替候補の一覧表示
sudo update-alternatives --display cuda
自動モードと手動モード
「ステップ2」の--configで選択すると「manual mode」になります。自動モード（最高優先度のバージョンを使用）に戻すには：
sudo update-alternatives --auto cuda
sudo update-alternatives --auto nvcc
Python仮想環境ごとのCUDAバージョン固定
システムのデフォルトを変えたくないが、特定のプロジェクトでは常に特定のCUDAバージョンを使いたい場合、仮想環境のactivate時に環境変数を上書きする方法が有効です。
# 仮想環境の activate スクリプト内や、プロジェクトの .env ファイルで設定
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
「ライブラリが見つからない」エラーが解消しない場合
update-alternatives設定後もエラーが続く場合、キャッシュが原因の可能性があります。
# 動的リンカのキャッシュを更新
sudo ldconfig
# Pythonのパッケージを再インストール（例: PyTorch）
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
まとめ・補足情報
update-alternativesを用いたCUDAバージョン管理は、複数のAIプロジェクトを並行して進める開発者や、異なるCUDAバージョンに依存するソフトウェアをテストする際の必須スキルです。この方法の最大の利点は、システムの基幹部分を汚すことなく、コマンド数行でクリーンにバージョン切り替えが可能な点にあります。
注意点として、CUDAのマイナーバージョン（例：11.8.0と11.8.1）間では、この方法で切り替えても大きな問題は起きにくいですが、メジャーバージョン（例：11.xと12.x）が異なる場合は、対応するcuDNNやNVIDIAドライバのバージョンにも注意を払う必要があります。また、Dockerコンテナを使用する開発フローでは、コンテナイメージ内に必要なCUDAバージョンを完結させる方が一般的であり、本記事の手法はホストマシン上での開発環境に適しています。
最後に、本設定は/usr/local以下にCUDAをインストールした標準的なケースを想定しています。NVIDIAの.runインストーラーやネットワークリポジトリを用いたインストール方法でも基本的な考え方は同じです。適切にパスを管理することで、「ライブラリがない」というストレスから解放され、AI開発本来の作業に集中できる環境を構築してください。