はじめに

Dockerコンテナ内で機械学習やGPUを使った処理を実行しようとした際に、コンテナからGPUを認識できず`、`nvidia-smi`コマンドを実行しても「command not found」や「No devices were found」というエラーに遭遇する方は多いのではないでしょうか。本記事では、Docker Compose环境下でNVIDIA GPUをコンテナに認識させるための設定方法をstep by stepで解説します。

問題の詳細

例えば、以下のようなdocker-compose.ymlを作成したとします：

version: '3.8'
services:
  ml-app:
    image: nvidia/cuda:11.0-base
    command: nvidia-smi

そして、`docker-compose up`を実行すると、以下のようなエラーが発生する場合があります：

Error response from daemon: could not select device driver with capabilities: [[gpu]]

または、コンテナは起動するものの、`nvidia-smi`を実行するとGPU情報が表示されないといった症状もあります。

結論

`docker-compose.yml`のservices配下に`deploy.resources.reservations.devices`設定を追加し、NVIDIA driverとgpu capabilityを指定することで、コンテナからGPUを認識させることが可能です。

前提条件

設定を進める前に、以下の環境が構築されていることを確認してください：

NVIDIA DriverがホストOSにインストールされている
nvidia-container-toolkitがインストールされている
Dockerがインストールされている
Docker Composeが利用可能（v1またはv2）

未インストーの場合は、各OSに応じたインストール手順を確認してください。特にnvidia-container-toolkitのインストール尤为重要です。

具体的な設定手順

ステップ1: docker-compose.ymlの編集

以下のyamlブロックをservices配下に追加します：

version: '3.8'
services:
  ml-app:
    image: nvidia/cuda:11.0-base
    command: nvidia-smi
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

設定項目の解説

driver: nvidia – NVIDIA GPUを使用するための指定
count: 1 – 使用するGPUの数（特定の1台のみ）。全GPUを使用する場合は`count: all`を指定
capabilities: [gpu] – GPU機能へのアクセスを有効化

ステップ2: Docker Composeのバージョンによる違い

Docker Compose v1（旧バージョン）の場合は、先頭の`version`指定が必要です。一方、Docker Compose v2（`docker compose`コマンド）の場合は、`version`指定は不要ですが、古い形式との互換性のために記載しておくことも。

ステップ3: コンテナの起動と確認

以下のコマンドでコンテナを起動します：

# Docker Compose v2の場合
docker compose up

# Docker Compose v1の場合
docker-compose up

正常にGPUが認識されていれば、以下のような出力が表示されます：

Fri Jan 10 12:00:00 2025
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.60.13    Driver Version: 525.60.13    CUDA Version: 12.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:01:00.0  On |                  N/A |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+

ステップ4: 複数のGPUを使用する場合

複数枚のGPUをコンテナに認識させたい場合は、`count`を`all`に変更します：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

補足・注意点

バージョン依存の情報

Docker Composeファイルの`version`指定は重要です。古いバージョン（Compose v1）では`version: ‘3.8’`以上的認知される仕様がありましたが、Compose v2では徐々にこの指定の重要性は低下しています
NVIDIA Container Toolkitは、Docker 19.03以降で標準サポートされています。それ以前のバージョンでは、nvidia-docker2パッケージのインストールが必要でした

環境による違い

Linux: 上記の設定で基本的に動作します。NVIDIA Container Toolkitのインストールが必要です
Windows (WSL2): WSL2上でDockerを実行する場合、Windows用のNVIDIA DriverとWSL2用のNVIDIA CUDA Toolkitの両方が必要な場合があります
macOS: NVIDIA GPU搭载のMacは限定的です。AMD GPUを使用している場合は、追加の設定が必要な場合があります

よくある落とし穴

nvidia-container-toolkit未インストール: 最も多い原因です。ホストOSにNVIDIA Driverだけでなく、nvidia-container-toolkitがインストールされていることを確認してください
Docker Desktopの設定: Docker Desktopを使用している場合、Settings > Resources > GPUからGPUアクセラレーションを有効にする必要があります
capabilitiesのスペルミス: `capabilities: [gpu]`と正しく記載してください。`capability`（単数形）ではありません
GPUが他のプロセスで使用中: 別のプロセスがGPUを使用している場合、コンテナからアクセスできないことがあります

トラブルシューティング

動作しない場合は、以下のコマンドで問題の切り分けができます：

# ホストOSでGPU認識確認
nvidia-smi

# DockerがGPUを認識しているか確認
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

# runtimeの確認
docker info | grep -i nvidia

まとめ

Docker ComposeでGPUを使用するには、`deploy.resources.reservations.devices`にNVIDIA driverとgpu capabilityを指定する設定を追加するのが最も標準的な方法です。基本的な設定は数行のyaml追加のみで完了しますが、前提条件としてnvidia-container-toolkitのインストールが必要です。記事が参考になれば幸いです。

【Docker Compose】GPU認識しない・nvidia-smiが効かない問題の解決法