【Docker/環境】JupyterLabでGPU対応AI開発環境を構築する手順とよくあるエラー解決法

問題の概要：JupyterLab環境でGPUが認識されない・利用できない

Dockerを使用してJupyterLabのAI開発環境を構築する際、特に深層学習モデルの学習や推論を行う場合、コンテナ内からGPUが認識されず、以下のようなエラーメッセージに遭遇することがあります。

RuntimeError: No CUDA GPUs are available
torch.cuda.is_available()  # False を返す
nvidia-smi: command not found
docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]].

この問題は、ホストマシンにNVIDIA GPUとドライバが正しくインストールされているにもかかわらず、DockerコンテナがGPUリソースにアクセスできない状態で発生します。結果として、PyTorchやTensorFlowなどのフレームワークがCPUでしか動作せず、計算速度が大幅に低下してしまいます。

原因の解説：DockerのGPUサポート不足と構成ミス

この問題の根本的な原因は、主に以下の3点に集約されます。

1. NVIDIA Container Toolkitの未インストール

従来のDockerエンジンは、デフォルトでGPUリソースをコンテナに公開する機能を持っていません。この橋渡し役となるのが「NVIDIA Container Toolkit」（旧NVIDIA Docker）です。このツールキットがインストールされていないと、DockerはGPUデバイスを認識できません。

2. ベースイメージの選択ミス

CUDAやcuDNNなどのNVIDIAライブラリがプリインストールされていない軽量なPythonイメージ（例: python:3.9-slim）を使用すると、コンテナ内にGPU計算の基盤が整いません。GPU対応の開発環境には、NVIDIAが提供するCUDAが含まれたベースイメージを選択する必要があります。

3. DockerコマンドまたはComposeファイルの設定不足

たとえツールキットがインストールされ、適切なイメージを使っていても、コンテナ実行時にGPUを有効化するオプション（--gpus all）や、Docker Composeファイル内での正しい設定がなければ、GPUは利用できません。

解決方法：ステップバイステップでのGPU対応環境構築

ステップ1: 前提条件の確認（ホストマシン）

まず、ホストマシン（Dockerを実行する物理マシンやVM）が以下の条件を満たしていることを確認します。

# 1. NVIDIAドライバがインストールされているか確認
nvidia-smi
# 出力例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 525.105.17   Driver Version: 525.105.17   CUDA Version: 12.0    |
# |-------------------------------+----------------------+----------------------+

# 2. Dockerエンジンがインストールされているか確認
docker --version
# Docker version 24.0.5, build 24.0.5-0ubuntu1~22.04.1

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

Ubuntuを例に、インストール手順を示します。他のディストリビューションは公式ガイドを参照してください。

# パッケージリポジトリとGPGキーを設定
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
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

# ツールキットをインストール
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Dockerデーモンを再起動して設定を適用
sudo systemctl restart docker

# インストール確認（オプション）
sudo nvidia-ctk --version

ステップ3: GPU対応Dockerイメージの選択とDockerfile作成

JupyterLabと主要AIフレームワーク、CUDA環境をまとめたDockerfileを作成します。NVIDIAが提供するnvidia/cudaイメージをベースにするのが確実です。

# Dockerfile
# CUDA 12.1 + cuDNN 8 + Ubuntu 22.04 をベースに、PythonとJupyterLabをインストール
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04

# 環境変数の設定
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# システムパッケージの更新とPython、必要ツールのインストール
RUN apt-get update && apt-get install -y 
    python3-pip 
    python3-dev 
    git 
    wget 
    curl 
    && rm -rf /var/lib/apt/lists/*

# pipのアップグレードとPythonパッケージのインストール
RUN pip3 install --upgrade pip
RUN pip3 install 
    jupyterlab 
    notebook 
    ipywidgets 
    torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 
    tensorflow[and-cuda]==2.13.0 
    pandas 
    numpy 
    matplotlib 
    scikit-learn 
    seaborn

# JupyterLabの作業ディレクトリとポート設定
WORKDIR /workspace
EXPOSE 8888

# JupyterLabの起動コマンド
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root", "--NotebookApp.token=''", "--NotebookApp.password=''"]

ステップ4: Dockerイメージのビルドと実行

Dockerfileがあるディレクトリでイメージをビルドし、GPUオプションを付けて実行します。

# イメージのビルド（タグ名は任意）
docker build -t jupyterlab-gpu:latest .

# GPUを有効にしてコンテナを起動
docker run --gpus all -it -p 8888:8888 -v $(pwd):/workspace jupyterlab-gpu:latest

起動後、ターミナルに表示されるURL（例: http://127.0.0.1:8888/lab?token=...）にブラウザでアクセスします。

ステップ5: コンテナ内でのGPU動作確認

JupyterLab内で新しいノートブックを作成し、以下のコードを実行してGPUが認識されているか確認します。

# Pythonコード例 (PyTorchの場合)
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU device name: {torch.cuda.get_device_name(0)}")
    print(f"CUDA version: {torch.version.cuda}")

# Pythonコード例 (TensorFlowの場合)
import tensorflow as tf
print(f"TensorFlow version: {tf.__version__}")
print(f"GPU available: {tf.config.list_physical_devices('GPU')}")

期待される出力は以下の通りです：

PyTorch version: 2.1.0+cu121
CUDA available: True
GPU device name: NVIDIA GeForce RTX 4090
CUDA version: 12.1

TensorFlow version: 2.13.0
GPU available: [PhysicalDevice(name='/physical_device:GPU:0', device_type='GPU')]

ステップ6: Docker Composeを使った管理（オプション）

環境を再現しやすくするため、docker-compose.ymlを定義することをお勧めします。

# docker-compose.yml
version: '3.8'

services:
  jupyterlab:
    build: .
    container_name: jupyterlab-gpu-container
    runtime: nvidia # NVIDIA Container Runtimeを指定
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8888:8888"
    volumes:
      - ./workspace:/workspace
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    stdin_open: true
    tty: true

Composeを使用して起動・停止するコマンドは以下の通りです。

# ビルドして起動
docker compose up -d --build

# ログを確認
docker compose logs -f

# 停止
docker compose down

よくあるエラーとその解決策

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

原因: NVIDIA Container Toolkitが正しくインストールされていない、またはDockerデーモンの再起動が行われていない。
解決策: ステップ2のインストール手順を再度実行し、sudo systemctl restart dockerでDockerデーモンを再起動します。

エラー2: コンテナ内でnvidia-smiが実行できない

原因: コンテナ実行時に--gpus allオプションが指定されていない。または、Docker Composeでruntimeやdeploy.resourcesの設定が不足している。
解決策: docker runコマンドに--gpus allを必ず追加するか、Composeファイルの設定を見直します。

エラー3: PyTorch/TensorFlowがCUDAを認識しない

原因: ベースイメージのCUDAバージョンと、pipでインストールしたPyTorch/TensorFlowのCUDAバージョンが一致していない。
解決策: Dockerfile内で、ベースイメージのCUDAバージョン（例: nvidia/cuda:12.1.1...）と、インストールするパッケージのバージョンを合わせます。PyTorchの場合は公式サイトで対応するインストールコマンドを確認してください。

まとめ・補足情報

JupyterLabでGPU対応のAI開発環境をDockerで構築するには、1) ホスト側のNVIDIAドライバ、2) NVIDIA Container Toolkit、3) CUDAベースの適切なDockerイメージ、4) 正しい実行時オプションの4つがすべて揃っている必要があります。本記事の手順に従うことで、再現性が高く、ホスト環境を汚さない隔離されたGPU開発環境を手に入れることができます。

補足:

• イメージサイズを小さくしたい場合は、nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04の代わりにnvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04を使用すると開発用ライブラリも含まれますが、イメージが大きくなります。-runtimeは実行に必要な最小限のライブラリを含みます。
• プロジェクトごとに異なるバージョンのフレームワークが必要な場合は、Dockerfileを分けたり、requirements.txtをボリュームマウントして動的にインストールする方法を検討してください。
• 本番環境やチームでの利用を考えると、ビルド済みイメージをDocker Hubや社内レジストリにプッシュして共有するのが効率的です。

この環境構築により、データ分析、モデル開発、トレーニング、評価までを一貫してJupyterLab上で行い、GPUの高速計算能力を最大限に活用できるようになります。