このエラーが発生する理由
docker run --gpus allを実行した際、コンテナが起動する代わりに素っ気ないエラーメッセージが表示されることがあります。これは基本的に、DockerがGPU対応のドライバを探しているものの、見つけられないことを意味します。デフォルトの状態では、Dockerは標準のruncランタイムを使用します。runcはCPUやRAMの隔離には優れていますが、NVIDIAのハードウェアと通信する方法を認識していません。
これを修正するには、NVIDIA Container Toolkitという「翻訳者」が必要です。これがないと、Dockerは--gpusフラグが何を意味するのかさえ理解できません。
ステップ 1：ホストドライバの確認
すべてはベースとなるドライバから始まります。ホストOSがGPUを認識できていなければ、Dockerも当然認識できません。ターミナルを開いて以下を実行してください：
nvidia-smi
ドライバのバージョン（例：535.129.03）と、RTX 3080やA100などのGPUモデルが表示されたステータス表が表示されるはずです。もし「command not found」や通信エラーが表示される場合は、ここで作業を中断してください。Dockerを操作する前に、NVIDIAのプロプライエタリドライバをインストールする必要があります。
ステップ 2：NVIDIA Container Toolkitのインストール
Ubuntu 22.04、Debian、CentOSなど、最近のほとんどのLinux環境では同様の手順を踏みます。システムがツールキットのダウンロード先を認識できるように、NVIDIAの公式パッケージリポジトリを追加する必要があります。
まず、GPGキーとリポジトリリストを設定します：
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/stable/deb/nvidia-container-toolkit.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
次に、パッケージリストを更新してツールキットをインストールします。ダウンロードサイズは小さく、通常は20MB以下です。
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
ステップ 3：NVIDIAランタイムの登録
ツールキットをインストールしただけでは不十分です。Dockerに対して、実際にそれを使用するように指示する必要があります。NVIDIAは、daemon.jsonファイルの構成を自動化する便利なユーティリティを提供しています。
sudo nvidia-ctk runtime configure --runtime=docker
このコマンドにより/etc/docker/daemon.jsonが更新されます。「nvidia」という名前の新しいランタイムが追加され、ツールキットのバイナリを参照するようになります。興味があれば、cat /etc/docker/daemon.jsonを実行して新しい設定ブロックを確認してみてください。
ステップ 4：再起動と動作確認
Dockerは起動時にのみ設定を読み込みます。変更を適用するためにサービスを再起動します：
sudo systemctl restart docker
いよいよ本番です。小さなCUDAコンテナを実行して、GPUにアクセスできるか確認しましょう。公式のNVIDIAイメージを使用して、コンテナの内部からnvidia-smiを実行します。
docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu22.04 nvidia-smi
ターミナルに見慣れたGPUの表が表示されれば成功です。表示されれば、ブリッジが正常に構築されたことになります。
Docker Composeのトラブルシューティング
もしDocker Composeを使用していて、まだエラーが発生する場合は、YAMLファイルに原因がある可能性があります。Composeでは、ハードウェアを予約するために特定のdeployブロックが必要です。docker-compose.ymlがバージョン3.8以上を使用していることを確認してください。
services:
gpu-worker:
image: nvidia/cuda:12.0-base-ubuntu22.04
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
安定稼働のためのプロのヒント
- **WSL2ユーザー：**UbuntuのWSLディストリビューション内にはNVIDIAドライバをインストールしないでください。Windows側に最新のGame ReadyドライバまたはStudioドライバをインストールします。Docker Desktopが残りの処理を自動的に行います。
- **カーネルアップデート：**LinuxカーネルのアップデートによってNVIDIAドライバが破損することがあります。ホスト側で
nvidia-smiが動作しなくなった場合、Dockerも失敗します。通常、sudo apt install --reinstall nvidia-driver-<version>を実行することで解決します。 - **パーシステンス（永続性）：**本番環境では、
sudo nvidia-smi -pm 1を使用してパーシステンスモードを有効にしてください。これによりドライバがロードされたままになり、コンテナの起動遅延が100〜200msほど短縮されます。