セットアップガイド

【Docker/環境】JupyterLabでGPU対応AI開発環境を構築する手順とトラブルシューティング

· 16分で読めます · 3 閲覧

問題の概要：JupyterLab環境でGPUが利用できない

Dockerを使用してJupyterLabのAI開発環境を構築した際、GPUが認識されず、PyTorchやTensorFlowでtorch.cuda.is_available()がFalseを返すという問題が頻発します。特に、NVIDIA GPUを搭載したマシンでDockerコンテナ内からGPUリソースにアクセスできない状態は、深層学習モデルの訓練を著しく非効率にします。本記事では、この問題の原因を解説し、確実にGPU対応環境を構築するための手順をステップバイステップで紹介します。

原因の解説

DockerコンテナがホストマシンのGPUを認識しない主な原因は以下の3つです。

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

従来のnvidia-dockerは廃止され、現在はNVIDIA Container Toolkitが標準です。これがインストールされていないと、--gpusオプションが使えず、コンテナはGPUデバイスを認識できません。

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

CUDAとcuDNNがプリインストールされていないベースイメージ（例: 公式のpython:3.9-slim）を使うと、コンテナ内でGPUライブラリを一から構築する必要があり、バージョン不一致エラーが発生しやすくなります。

3. Dockerコマンドのオプション不足

単にdocker runするだけではGPUは接続されません。明示的に--gpus allオプションを指定する必要があります。また、ホストとコンテナ間のCUDAバージョン不一致もよくある落とし穴です。

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

ステップ1: ホストマシンの環境確認

まず、ホストマシン（Dockerを実行する物理マシンまたはVM）の環境を確認します。

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

# Dockerのインストール確認
docker --version

# NVIDIA Container Toolkitのインストール確認（インストールされていない場合）
# 以下の公式手順に従ってインストール: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
# Ubuntuの場合のインストールコマンド例
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

ステップ2: 適切なDockerfileの作成

NVIDIAが提供するCUDA付きのベースイメージを使用することが成功の鍵です。以下は、PyTorchとJupyterLabを含む環境を構築するDockerfileの例です。

# Dockerfile
# CUDA 11.8 + cuDNN 8 + Ubuntu 22.04 のベースイメージを使用
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

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

# システムパッケージの更新と必須ツールのインストール
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 
    torch==2.0.1+cu118 
    torchvision==0.15.2+cu118 
    torchaudio==2.0.2+cu118 
    --index-url https://download.pytorch.org/whl/cu118
RUN pip3 install 
    jupyterlab==4.0.5 
    ipywidgets==8.1.1 
    matplotlib==3.7.2 
    pandas==2.0.3 
    scikit-learn==1.3.0 
    tensorflow==2.13.0

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

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

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

Dockerfileがあるディレクトリで以下のコマンドを実行します。

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

# コンテナの実行（重要なのは --gpus all オプション）
docker run -d 
  --gpus all 
  -p 8888:8888 
  -v $(pwd)/workspace:/workspace 
  --name my-jupyterlab-gpu 
  jupyterlab-gpu:latest

# ログを確認してJupyterLabの起動を確認
docker logs my-jupyterlab-gpu
# 出力に `http://127.0.0.1:8888/lab?token=...` のような行があれば成功

ステップ4: 動作確認とトラブルシューティング

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

# 確認用Pythonコード
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()}")

import tensorflow as tf
print(f"nTensorFlow version: {tf.__version__}")
print(f"TF GPU available: {tf.config.list_physical_devices('GPU')}")

期待される出力例：

PyTorch version: 2.0.1+cu118
CUDA available: True
CUDA version: 11.8
GPU device name: NVIDIA GeForce RTX 4090
GPU device count: 1

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

ステップ5: よくあるエラーと対処法

エラー1: docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]].
原因: NVIDIA Container Toolkitが正しくインストール/設定されていない。
解決: ステップ1のインストール手順を再度実行し、sudo systemctl restart dockerでDockerデーモンを再起動。

エラー2: CUDA error: no kernel image is available for execution on the device
原因: コンテナ内のCUDA/PyTorchバージョンが、ホストのGPUアーキテクチャ（Compute Capability）をサポートしていない。
解決: より新しいCUDAバージョンのベースイメージ（例: nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04）を使用し、対応するPyTorchバージョン（--index-url https://download.pytorch.org/whl/cu121）をインストールする。

エラー3: torch.cuda.is_available()がFalseを返すが、nvidia-smiはコンテナ内で実行できる
原因: PyTorchのCUDAバージョンと、ベースイメージのCUDAバージョンが不一致。
解決: Dockerfile内のpip install torch...のURLにあるCUDAバージョン（例: cu118）と、FROM行のCUDAバージョン（例: 11.8.0）を一致させる。

コード例・コマンド例：一括セットアップスクリプト

環境構築を自動化するために、以下のようなシェルスクリプト（setup.sh）を作成することも有用です。

#!/bin/bash
# setup.sh - JupyterLab GPU環境自動構築スクリプト

set -e  # エラー発生時にスクリプトを停止

echo "1. Dockerイメージをビルドします..."
docker build -t jupyterlab-gpu:latest .

echo "2. 既存の同名コンテナを削除します（存在する場合）..."
docker stop my-jupyterlab-gpu 2>/dev/null || true
docker rm my-jupyterlab-gpu 2>/dev/null || true

echo "3. 新しいコンテナを起動します..."
docker run -d 
  --gpus all 
  -p 8888:8888 
  -v $(pwd)/workspace:/workspace 
  --name my-jupyterlab-gpu 
  jupyterlab-gpu:latest

echo "4. 起動ログを確認します..."
sleep 3  # 起動待機
docker logs my-jupyterlab-gpu --tail 20

echo "5. ブラウザで http://localhost:8888 にアクセスしてください。"
echo "完了しました。"

スクリプトを実行可能にして実行します。

chmod +x setup.sh
./setup.sh

まとめ・補足情報

JupyterLabでGPU対応のAI開発環境をDockerで構築するには、1) NVIDIA Container Toolkitのインストール、2) CUDA対応ベースイメージの選択、3) 正しい--gpusオプション付きでのコンテナ実行の3点が必須です。本記事で紹介した手順に従うことで、再現性の高い環境を迅速に構築できます。

補足情報:

  • パフォーマンスチューニング: データセットの読み込みがボトルネックになる場合は、-vオプションでマウントするホスト側のディレクトリをSSD上に配置し、--shm-sizeオプションで共有メモリを増やす（例: --shm-size=8g）ことを検討してください。
  • 複数GPU環境: 特定のGPUのみを使用したい場合は、--gpus allの代わりに--gpus '"device=0,1"'のようにデバイスIDを指定できます。
  • Docker Composeの利用: 環境をコードで管理したい場合は、docker-compose.ymlを以下のように作成すると便利です。
# docker-compose.yml
version: '3.8'
services:
  jupyterlab:
    build: .
    runtime: nvidia  # これがGPUサポートのキー
    ports:
      - "8888:8888"
    volumes:
      - ./workspace:/workspace
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

この環境構築により、チームメンバー間での開発環境の統一や、実験の再現性確保が容易になり、AIモデル開発の生産性を大幅に向上させることができます。

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