セットアップガイド

【Docker/環境】NVIDIA Container ToolkitインストールとGPUパススルー設定エラー完全解決ガイド

· 13分で読めます · 2 閲覧

問題の概要：Dockerコンテナ内でGPUが認識されない

AI開発や機械学習の環境構築において、Dockerコンテナ内でGPUリソースを利用しようとすると、以下のようなエラーに遭遇することが頻繁にあります。

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

あるいは、PyTorchやTensorFlowをコンテナ内で実行した際に、GPUが利用できないという警告やエラーが表示されます。

RuntimeError: No CUDA GPUs are available

W tensorflow/core/common_runtime/gpu/gpu_device.cc:1858] Cannot dlopen some GPU libraries. Please make sure the missing libraries mentioned above are installed properly if you would like to use GPU.

これらの問題は、ホストマシンにNVIDIA GPUドライバがインストールされていても、DockerコンテナがGPUデバイスやCUDAライブラリにアクセスするための仕組み（NVIDIA Container Toolkit）が正しく設定されていないために発生します。本記事では、この根本的な原因を解説し、確実に解決するためのステップバイステップガイドを提供します。

原因の解説：DockerのデフォルトではGPUは隔離される

Dockerは、その設計上、コンテナをホストシステムから隔離することで高いセキュリティと再現性を実現しています。このため、ホストマシンの物理デバイス（GPUなど）や特定のデバイスドライバは、明示的な設定なしではコンテナ内から見えません。

NVIDIA GPUをコンテナ内で利用するためには、以下の3つの要素をコンテナに提供する必要があります。

  1. GPUデバイスファイル (例: `/dev/nvidia0`, `/dev/nvidia-uvm`)
  2. NVIDIAドライバライブラリ (例: `libcuda.so`)
  3. CUDA Toolkitライブラリ (コンテナイメージ内にインストールするか、ホストからマウント)

NVIDIA Container Toolkit（旧称：nvidia-docker2）は、Dockerランタイムと連携し、上記1と2をコンテナに自動的にマウント・設定するためのツールキットです。これがインストール・設定されていないことが、「コンテナ内でGPUが使えない」問題の最も一般的な原因です。

解決方法：NVIDIA Container Toolkitのインストールと設定

以下の手順は、Ubuntu 20.04/22.04を例としていますが、他のディストリビューションでも基本的な流れは同様です。各ステップのコマンドを順番に実行してください。

ステップ1: 前提条件の確認

まず、ホストマシンにNVIDIA GPUドライバとDocker Engineが正しくインストールされていることを確認します。

# NVIDIA GPUドライバの確認
nvidia-smi

# Dockerの確認
docker --version
sudo systemctl status docker

nvidia-smiコマンドでGPU情報が表示され、docker --versionでバージョンが表示されることを確認してください。

ステップ2: NVIDIA Container Toolkitのリポジトリ設定

パッケージマネージャを通じて安全にインストールするために、NVIDIAの公式リポジトリを追加します。

# ディストリビューションとアーキテクチャを設定
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
echo "Distribution: $distribution"

# 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/$distribution/libnvidia-container.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

ステップ3: NVIDIA Container Toolkitのインストール

リポジトリを追加したら、パッケージリストを更新してツールキットをインストールします。

# パッケージリストの更新とインストール
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

ステップ4: Dockerランタイムの設定

インストールが完了したら、DockerがNVIDIA Container Runtimeを使用するように設定します。

# nvidia-container-runtimeをDockerの設定に登録
sudo nvidia-ctk runtime configure --runtime=docker

# Dockerデーモンの再起動（設定を反映）
sudo systemctl restart docker

nvidia-ctkコマンドは、/etc/docker/daemon.json ファイルを自動的に編集し、`nvidia` をデフォルトのランタイムとして追加します。

ステップ5: 動作確認

最も簡単な方法で、GPUがコンテナ内から見えるかテストします。

# ベースCUDAコンテナを実行してnvidia-smiを実行
sudo docker run --rm --runtime=nvidia --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

このコマンドで、ホストでnvidia-smiを実行した時と同様のGPU情報が表示されれば成功です。--gpus allオプションが、すべてのGPUをコンテナに割り当てる指示です。

コード例・コマンド例

基本的なDocker runコマンド

GPUを有効にしてコンテナを起動する主な方法は以下の2通りです。

# 方法1: --runtime=nvidia と --gpus オプションを使用（推奨）
docker run --rm --runtime=nvidia --gpus all my-ai-app:latest python train.py

# 方法2: 環境変数 NVIDIA_VISIBLE_DEVICES を使用
docker run --rm --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all my-ai-app:latest

# 特定のGPUのみを割り当てる（GPU ID 0番のみ）
docker run --rm --runtime=nvidia --gpus '"device=0"' my-ai-app:latest

# 複数の特定GPUを割り当てる（GPU ID 0番と1番）
docker run --rm --runtime=nvidia --gpus '"device=0,1"' my-ai-app:latest

Docker Composeでの設定例

Docker Composeを使用する場合は、docker-compose.ymlファイルで以下のようにデプロイ設定を記述します。

version: '3.8'
services:
  ai-training:
    image: pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - ./src:/app
    working_dir: /app
    command: python train.py

または、ランタイムを直接指定する方法もあります。

version: '3.8'
services:
  jupyter:
    image: jupyter/tensorflow-notebook:latest
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8888:8888"
    volumes:
      - ./notebooks:/home/jovyan/work

まとめ・補足情報

NVIDIA Container Toolkitは、Docker環境でGPUリソースをシームレスに利用するための必須の橋渡し役です。インストールと設定は比較的シンプルですが、以下のポイントを押さえることで、よりスムーズなAI開発環境を構築できます。

  • ドライバの互換性: ホストのNVIDIAドライババージョンと、コンテナ内で使用するCUDAバージョンの互換性に注意してください。古いドライバでは新しいCUDA機能が使えない場合があります。
  • 「–gpus all」オプション: Docker 19.03以降では--gpusオプションが公式サポートされています。これが最もクリーンな指定方法です。
  • トラブルシューティング: 設定後もGPUが認識されない場合、sudo docker info | grep -i runtimeでNVIDIAランタイムが有効か確認し、/etc/docker/daemon.jsonの設定内容をチェックしてください。
  • Kubernetes環境: Kubernetes上でGPUを利用する場合は、さらにNVIDIA Device Pluginのインストールが必要になります。

本ガイドの手順に従うことで、ホストマシンのGPUパワーをDockerコンテナ内で最大限に活用できるようになり、再現性の高いAI開発・実験環境を手に入れることができます。環境構築の自動化スクリプトにこれらのコマンドを組み込むことで、チーム全体の開発効率向上にも貢献できるでしょう。

この記事は役に立ちましたか？