【Docker/環境】JupyterLabでGPU対応AI開発環境を構築する手順と「Cannot connect to GPU」エラー解決法

1. 問題の概要：JupyterLab環境でのGPU認識エラー

Dockerを使用してJupyterLabのAI開発環境を構築する際、特に深層学習モデルの学習や推論を行う場合、GPUを認識せずCPUのみで動作してしまう問題が頻発します。具体的には、JupyterLabのセル内でtorch.cuda.is_available()を実行してもFalseが返され、以下のようなエラーメッセージが表示されることがあります。

# 典型的なエラーメッセージ例
>>> import torch
>>> torch.cuda.is_available()
False

# nvidia-smiコマンド実行時のエラー例（Dockerコンテナ内）
$ nvidia-smi
Failed to initialize NVML: Driver/library version mismatch
または
NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver.

この状態では、GPUの並列計算能力を活かせず、大規模なモデル訓練が現実的な時間で完了しなくなります。本記事では、この根本原因を解説し、確実にGPU対応環境を構築する手順をステップバイステップで紹介します。

2. 原因の解説：DockerとGPU連携の仕組み

DockerコンテナがホストマシンのGPUを認識できない主な原因は、以下の3つに集約されます。

2.1 NVIDIA Container Toolkitの未インストール

従来のnvidia-docker2は非推奨となり、現在はNVIDIA Container Toolkitが標準です。これはDockerランタイムとNVIDIA GPUドライバーを連携させるための必須ミドルウェアです。これがインストールされていないと、DockerはGPUデバイスを認識する方法がありません。

2.2 Dockerランタイムの設定不備

NVIDIA Container Toolkitをインストールした後、Dockerデーモンの設定ファイル（/etc/docker/daemon.json）を更新し、nvidiaをデフォルトのランタイムとして設定する必要があります。この設定が抜けていると、--gpusオプションが機能しません。

2.3 ベースイメージの選択ミス

CUDAとcuDNNがプリインストールされていない軽量なPythonベースイメージ（例: python:3.9-slim）を使用すると、コンテナ内にGPU計算ライブラリが存在せず、たとえGPUデバイスが認識されても計算を実行できません。NVIDIAが提供する公式CUDAイメージや、PyTorch/TensorFlowのGPU対応公式イメージを使用することが必須です。

3. 解決方法：ステップバイステップ構築手順

以下は、Ubuntu 20.04/22.04 LTSをホストOSとする環境を想定した、完全な構築手順です。

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

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

# NVIDIAドライバーとCUDAバージョンの確認
$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.105.17   Driver Version: 525.105.17   CUDA Version: 12.0    |
|-------------------------------+----------------------+----------------------+
# ドライバーが表示されない場合は、以下を実行
$ ubuntu-drivers devices
# 推奨ドライバーをインストール
$ sudo apt install nvidia-driver-525

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

公式リポジトリを追加し、必要なパッケージをインストールします。

# パッケージリポジトリと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

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

DockerデーモンにNVIDIAランタイムを設定します。

# nvidia-container-runtimeを設定
$ sudo nvidia-ctk runtime configure --runtime=docker
# 設定を反映させるためにDockerデーモンを再起動
$ sudo systemctl restart docker
# 設定が正しく登録されたか確認
$ sudo docker info | grep -i runtime
 Runtimes: nvidia runc io.containerd.runc.v2
 Default Runtime: runc

ステップ4: GPU対応JupyterLab Dockerfileの作成

PyTorchの公式GPUイメージをベースに、JupyterLab環境を構築するDockerfileを作成します。

# Dockerfile
# CUDA 12.1 + PyTorch 2.0 + Python 3.10の公式イメージをベース
FROM pytorch/pytorch:2.0.1-cuda12.1-cudnn8-runtime

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

# JupyterLabとAI開発用ライブラリのインストール
RUN pip install --no-cache-dir --upgrade pip && 
    pip install --no-cache-dir 
    jupyterlab 
    ipywidgets 
    jupyter-archive 
    matplotlib 
    seaborn 
    scikit-learn 
    pandas 
    numpy 
    scipy 
    tqdm 
    tensorboard

# 作業ディレクトリの設定
WORKDIR /workspace

# JupyterLabの起動設定（ポート8888、パスワードなし、IP全許可）
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root", "--NotebookApp.token=''", "--NotebookApp.password=''"]

ステップ5: Dockerイメージのビルドとコンテナ起動

Dockerイメージをビルドし、GPUを有効化してコンテナを起動します。

# Dockerイメージのビルド（タグ付け）
$ docker build -t jupyterlab-gpu:latest .

# GPUを有効にしてコンテナを起動（全てのGPUを利用）
$ docker run -d 
  --gpus all 
  -p 8888:8888 
  -v $(pwd)/workspace:/workspace 
  --name jupyter-gpu-container 
  --restart unless-stopped 
  jupyterlab-gpu:latest

# または、特定のGPUのみを指定（GPU ID 0のみ利用）
# $ docker run -d --gpus '"device=0"' -p 8888:8888 ...（省略）

# 起動ログの確認（JupyterLabのトークン情報など）
$ docker logs jupyter-gpu-container

ステップ6: 動作確認

ブラウザでhttp://localhost:8888にアクセスし、JupyterLabが起動していることを確認します。新しいノートブックを作成し、以下のコードを実行してGPUが認識されているかテストします。

# テスト用Pythonコード（JupyterLabセル内で実行）
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"CUDA version: {torch.version.cuda}")
    print(f"GPU device name: {torch.cuda.get_device_name(0)}")
    print(f"GPU device count: {torch.cuda.device_count()}")
    # 簡単なテンソル計算でGPUを実際に使用
    x = torch.randn(10000, 10000).cuda()
    y = torch.randn(10000, 10000).cuda()
    z = torch.matmul(x, y)
    print(f"Matrix multiplication on GPU successful. Result shape: {z.shape}")
else:
    print("ERROR: GPU is not available. Check your Docker configuration.")

4. トラブルシューティング：よくあるエラーと対処法

エラー1: 「Failed to initialize NVML: Driver/library version mismatch」

原因: ホストのNVIDIAドライバーと、コンテナ内で期待されるライブラリのバージョン不一致。
解決法: ホストのドライバーを再起動するか、DockerイメージのCUDAバージョンをホストのドライバーがサポートするものに合わせます。

$ sudo rmmod nvidia_drm nvidia_modeset nvidia_uvm nvidia
$ sudo nvidia-smi  # これでドライバーが再ロードされる

エラー2: 「Docker: Error response from daemon: could not select device driver…」

原因: NVIDIA Container Toolkitが正しくインストールされていない、またはDockerランタイム設定が未反映。
解決法: ステップ2と3を再確認し、Dockerデーモンの再起動を忘れずに行います。

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker

エラー3: JupyterLabからはGPUを認識するが、計算時にCUDAエラーが発生

原因: コンテナ内のCUDA/cuDNNと、PyTorch/TensorFlowのバージョン互換性問題。
解決法: ベースイメージを、フレームワーク公式が提供する特定バージョンのものに固定します（例: pytorch/pytorch:2.0.1-cuda11.8-cudnn8-devel）。

5. まとめ・補足情報

JupyterLabでGPU対応のAI開発環境をDockerで構築するには、1) ホスト側のNVIDIAドライバー、2) NVIDIA Container Toolkit、3) 適切なGPU対応ベースイメージの3点が揃っていることが不可欠です。本手順に従うことで、再現性が高く、移植性に優れた開発環境を手に入れることができます。

補足:

データの永続化には、-v $(pwd)/data:/dataのようにボリュームマウントを追加することをお勧めします。
複数のプロジェクトで環境を分けたい場合は、docker-compose.ymlファイルを作成し、プロジェクトごとに管理すると効率的です。
リソース制限をかけたい場合は、--shm-size=8g（共有メモリ）や--memory=16g（RAM制限）などのオプションをdocker runに追加します。

この環境構築により、ローカルマシンのGPUリソースを最大限活用した、快適なAIモデル開発と実験が可能になります。