遭遇した問題

vLLMをインストールいざ実行しようとimport vllmしたところ、以下のようなエラーが発生しました。

ImportError: libcuda.so.1: cannot open shared object file: No such file or directory

また、異なる環境では次のようなエラーも確認されています：

ImportError: CUDA library mismatch detected! vLLM was compiled against CUDA 12.x but the system has CUDA 13.x

環境例：

OS: Ubuntu 22.04
GPU: NVIDIA RTX 4090
CUDA Driver: 535.x
PyTorch: 2.x
vLLM: 0.11.0

結論

vLLMはCUDAおよびPyTorchのバージョン間にバイナリ非互換性があるため、新しいクリーンな環境を作成し、環境にあったCUDA対応バージョンのvLLMをインストールすることで解決できます。

具体的な手順

ステップ1：現在のCUDA環境を確認

# CUDAバージョンの確認
nvcc --version
nvidia-smi

# PyTorchのCUDAバージョンを確認
python -c "import torch; print(torch.version.cuda)"

ステップ2：クリーンな環境を作成

# conda環境の作成（推奨）
conda create -n vllm_env python=3.11 -y
conda activate vllm_env

# またはvenvの場合
python -m venv vllm_env
source vllm_env/bin/activate

ステップ3：環境にあったvLLMをインストール

# CUDA 12.1/12.2対応の場合
pip install vllm==0.11.0 --extra-index-url https://wheels.vllm.ai/cu121

# CUDA 12.4対応の場合
pip install vllm==0.11.0 --extra-index-url https://wheels.vllm.ai/cu124

# CUDA 12.8対応の場合（Driver 535対応）
pip install vllm==0.11.0 --extra-index-url https://wheels.vllm.ai/cu128

# 最新版vLLMの場合（CUDA 12.9+対応）
pip install vllm --extra-index-url https://wheels.vllm.ai/cu124

ステップ4：動作確認

python -c "import vllm; print('vLLM version:', vllm.__version__)"

ステップ5：環境変数の確認（必要な場合）

# CUDAライブラリのパスが通っているか確認
echo $LD_LIBRARY_PATH

# 必要に応じて追加
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

補足・注意点

バージョン依存について

vLLM 0.11.0はCUDA 12.9以上のプリビルドホイールを使用しています
Driver 535環境ではCUDA 12.9が動作しないため、CUDA 12.1/12.2/12.4対応のホイールを明示的に指定する必要があります
ARM64環境（NVIDIA GB10など）ではCUDA 13.xとvLLMのCUDA 12.xコンパイル済みの不一致が発生的报告があります

環境の差異による落とし穴

同じPyTorchバージョンでもビルド設定が異なる場合、バイナリ非互換性が発生します
既存のPython環境（既存のPyTorchやCUDAライブラリ済み環境）へのインストールは推奨されません
Dockerコンテナを使用する場合、ホスト環境のCUDAバージョンとコンテナ内のCUDAバージョン一致させることが重要です

よくある問題と対策

「libcuda.so.1が見つからない」エラー：CUDA Toolkitが正しくインストールされているか確認し、ldconfigでライブラリパスを更新
「CUDA out of memory」エラー：バッチサイズ减小または--gpu-memory-utilizationオプションでメモリ使用量を調整
インストールが永遠に終わらない：ネットワーク問題の可能性あり。Mirroredインデックスを試すか、ソースからビルド（非常に時間がかる）

根本的な解決アプローチ

どのバージョン也不明な場合は、最も費用対効果の高い方法は

まずプリビルドホイールの可用性を確認（pip index versions vllm）
自分のCUDA Driverバージョンに合わせて適切なCUDA対応wheelを選択
難しい場合はソースからのビルドを検討（時間はかかるが柔軟に対応可能）

【vLLM】CUDAバージョン不一致エラーの解決法