DockerでJupyter環境を構築する方法
はじめまして、
株式会社dotConfにて、AIエンジニアをしている古菅(こすげ)です!
前回は「【2025年最新版】PyTorchとTensorFlowの違いを徹底比較|初心者におすすめはどっち?」を紹介しましたが、
今回はその続編として、DockerでJupyter環境を構築する方法をまとめました。
はじめに
機械学習やデータ分析を始める際、環境構築でつまずいた経験はありませんか?
こんな悩みを一発で解決してくれるのが、🐳 DockerとJupyterの組み合わせです。
この記事では、Docker初心者の方でも迷わず環境構築できるよう、実際のコード例を交えながら丁寧に解説していきます。
なぜDockerでJupyter環境を構築するのか?
Dockerを使う3つのメリット
1️⃣ 環境の再現性が高い
チーム全員が同じ環境で開発できるため、「私の環境では動くのに...」という問題がなくなります。Dockerfileを共有するだけで、誰でも同じ環境を再現できます。
2️⃣ 環境のリセットが簡単
環境が壊れてもコンテナを削除して作り直すだけで元通り。ホストマシンには一切影響しません。クリーンな状態からやり直せるので、試行錯誤も気軽にできます。
3️⃣ 複数バージョンの共存が可能
Python 3.8とPython 3.11を同時に使いたい、TensorFlow 2.10とPyTorch 2.0を切り替えたいといったケースでも、異なるコンテナを立ち上げるだけで簡単に実現できます。
従来とDockerの環境構築の比較
項目 | 従来の環境構築 | Docker環境構築 |
---|---|---|
セットアップ時間 | 30分〜1時間 | 5分 |
環境の再現性 | ❌ 低い(手順書が必要) | ✅ 高い(Dockerfileで自動化) |
チーム間の共有 | 😰 困難(環境差異が発生) | 😊 簡単(同じイメージを使用) |
環境のリセット | ⚠️ 危険(システムに影響) | ✅ 安全(コンテナだけ削除) |
複数バージョン管理 | ❌ 困難(仮想環境の切り替え) | ✅ 簡単(コンテナの切り替え) |
必要な事前準備
Dockerのインストール
まずはDockerをインストールしましょう。OSごとにインストール方法が異なります。
インストール後、ターミナルまたはコマンドプロンプトで以下のコマンドを実行して、正しくインストールされたか確認してください。
docker --version
# Docker version 24.0.x, build xxxxxxx のように表示されればOK
正しく表示されない場合は、Docker Desktopを起動してから再度お試しください。
方法1: 最速で環境を立ち上げる(1コマンドで完了)
まずは最も簡単な方法から始めましょう。たった1行のコマンドでJupyter環境が起動します。
docker run -p 8888:8888 jupyter/scipy-notebook
実用的なオプションを追加する
実際の開発では、ファイルの永続化などのためにオプションを追加して使うことが多いです。
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work --name my-jupyter jupyter/scipy-notebook
オプションの詳細説明
オプション | 説明 | 重要度 |
---|---|---|
-p 8888:8888 |
ホストの8888番ポートとコンテナの8888番ポートを接続(ブラウザからアクセス可能に) | ⭐⭐⭐ 必須 |
-v $(pwd):/home/jovyan/work |
現在のディレクトリをコンテナ内のwork フォルダにマウント(ファイルを永続化) |
⭐⭐⭐ 推奨 |
--name my-jupyter |
コンテナに名前を付ける(管理しやすくなる) | ⭐⭐ 推奨 |
--rm |
コンテナ終了時に自動削除(ディスク容量の節約) | ⭐ 任意 |
注意: Windowsの場合は $(pwd)
の代わりに %cd%
(コマンドプロンプト)または ${PWD}
(PowerShell)を使用してください。
コンテナの停止と再開
# コンテナを停止
docker stop my-jupyter
# コンテナを再開
docker start my-jupyter
# ログを確認(URLを再度確認したい場合)
docker logs my-jupyter
方法2: Dockerfileでカスタム環境を構築
プロジェクト特有のライブラリが必要な場合は、Dockerfileを使って独自の環境を作りましょう。
ステップ1: Dockerfileの作成
プロジェクトフォルダにDockerfile
という名前のファイルを作成します。
# ベースイメージの指定(Jupyter公式のデータサイエンス向けイメージ)
FROM jupyter/scipy-notebook:latest
# 作業ディレクトリの設定
WORKDIR /home/jovyan/work
# 追加のPythonライブラリをインストール
# --no-cache-dirオプションでキャッシュを削除し、イメージサイズを削減
RUN pip install --no-cache-dir \
pandas==2.0.3 \
numpy==1.24.3 \
matplotlib==3.7.2 \
seaborn==0.12.2 \
scikit-learn==1.3.0 \
tensorflow==2.13.0 \
torch==2.0.1 \
transformers==4.31.0
# Jupyter拡張機能のインストール(便利な機能を追加)
RUN pip install --no-cache-dir \
jupyter_contrib_nbextensions \
jupyter_nbextensions_configurator
# 拡張機能を有効化
RUN jupyter contrib nbextension install --user && \
jupyter nbextensions_configurator enable --user
# ポートの公開(8888番ポート)
EXPOSE 8888
# Jupyterの起動コマンド
# --ip=0.0.0.0: すべてのIPからアクセス可能に
# --no-browser: ブラウザを自動起動しない
# --allow-root: rootユーザーでの実行を許可
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]
ステップ2: イメージのビルドと実行
# イメージをビルド
# -t オプションでイメージに名前をつける
docker build -t my-jupyter .
# コンテナを起動
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work --name my-jupyter my-jupyter
requirements.txtを使った管理
ライブラリのバージョン管理をより簡単にするため、requirements.txt
ファイルを作成する方法もあります。
requirements.txt
pandas==2.0.3
numpy==1.24.3
matplotlib==3.7.2
seaborn==0.12.2
scikit-learn==1.3.0
tensorflow==2.13.0
torch==2.0.1
transformers==4.31.0
Dockerfile(requirements.txt版)
FROM jupyter/scipy-notebook:latest
WORKDIR /home/jovyan/work
# requirements.txtをコンテナにコピー
COPY requirements.txt .
# requirements.txtからライブラリをインストール
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8888
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]
方法3: Docker Composeで複数サービスを管理
データベースやキャッシュサーバーなど、複数のサービスと連携する場合は、Docker Composeが便利です。
ステップ1: docker-compose.ymlの作成
プロジェクトフォルダにdocker-compose.yml
を作成します。
version: '3.8'
services:
# Jupyterサービス
jupyter:
build: . # Dockerfileからイメージをビルド
ports:
- "8888:8888"
volumes:
- ./notebooks:/home/jovyan/work # ノートブック用
- ./data:/home/jovyan/data # データ用
environment:
- JUPYTER_ENABLE_LAB=yes # JupyterLabを有効化
- GRANT_SUDO=yes # sudo権限を付与
networks:
- ml-network
depends_on:
- postgres # PostgreSQLの起動を待つ
# PostgreSQLデータベース
postgres:
image: postgres:15
environment:
- POSTGRES_USER=jupyter_user
- POSTGRES_PASSWORD=jupyter_pass
- POSTGRES_DB=ml_database
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432" # ホストからもアクセス可能に
networks:
- ml-network
# Redisキャッシュサーバー
redis:
image: redis:7-alpine
ports:
- "6379:6379"
networks:
- ml-network
# ネットワークの定義
networks:
ml-network:
driver: bridge
# 永続化ボリュームの定義
volumes:
postgres_data:
ステップ2: 起動と管理
# すべてのサービスを起動
# -dオプションでバックグラウンド実行
docker-compose up -d
# ログを確認
docker-compose logs -f jupyter
# サービスの状態確認
docker-compose ps
# すべてのサービスを停止 🛑
docker-compose down
Docker Composeの便利コマンド集
# 特定のサービスだけ起動
docker-compose up jupyter
# サービスの再起動
docker-compose restart jupyter
# サービス内でコマンドを実行
docker-compose exec jupyter bash
# ボリュームも含めて全削除(データも削除されるので注意)
docker-compose down -v
# イメージを再ビルドして起動
docker-compose up -d --build
Jupyter内からPostgreSQLに接続する例
import pandas as pd
from sqlalchemy import create_engine
# PostgreSQLに接続
# サービス名(postgres)をホスト名として使用できる
engine = create_engine('postgresql://jupyter_user:jupyter_pass@postgres:5432/ml_database')
# SQLクエリを実行
df = pd.read_sql('SELECT * FROM my_table', engine)
実践的な設定とTips
1️⃣ パスワード認証の設定 🔒
デフォルトのトークン認証に加えて、パスワード認証を設定すると、より使いやすくなります。
パスワードハッシュの生成
# Jupyter内または別のPython環境で実行
from jupyter_server.auth import passwd
passwd()
# パスワードを入力すると、ハッシュ値が表示される
# 例: 'argon2:$argon2id$v=19$...'
Dockerfileに追加
FROM jupyter/scipy-notebook:latest
# Jupyter設定ファイルの作成
RUN jupyter notebook --generate-config
# パスワードの設定(生成したハッシュ値に置き換える)
RUN echo "c.ServerApp.password = 'argon2:\$argon2id\$v=19\$...'" >> \
/home/jovyan/.jupyter/jupyter_server_config.py
# トークン認証も併用する場合はこちら
# RUN echo "c.ServerApp.token = 'your-custom-token'" >> \
# /home/jovyan/.jupyter/jupyter_server_config.py
2️⃣ GPU対応環境の構築
ディープラーニングでGPUを使いたい場合の設定例です。
前提条件
- NVIDIA GPUを搭載したマシン
- NVIDIA Dockerのインストール(公式ドキュメント)
Dockerfile(GPU版)
# CUDA対応のベースイメージを使用
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04
# Pythonとpipのインストール
RUN apt-get update && apt-get install -y \
python3-pip \
python3-dev \
&& rm -rf /var/lib/apt/lists/*
# JupyterLabとGPU対応ライブラリのインストール
RUN pip3 install --no-cache-dir \
jupyterlab \
numpy \
pandas \
matplotlib
# TensorFlow(GPU版)
RUN pip3 install --no-cache-dir tensorflow[and-cuda]
# PyTorch(GPU版)
RUN pip3 install --no-cache-dir \
torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/cu118
EXPOSE 8888
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]
起動コマンド
# --gpus allオプションでGPUを使用可能に
docker run --gpus all -p 8888:8888 -v $(pwd):/workspace my-gpu-jupyter
GPU利用確認方法
# PyTorchでの確認
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
print(f"GPU name: {torch.cuda.get_device_name(0)}")
# TensorFlowでの確認
import tensorflow as tf
print(f"GPU devices: {tf.config.list_physical_devices('GPU')}")
3️⃣ メモリとCPUの制限
リソースを制限して、システムを安定運用しましょう。
# メモリを4GB、CPUを2コアに制限
docker run -p 8888:8888 \
--memory="4g" \
--memory-swap="4g" \
--cpus="2.0" \
-v $(pwd):/home/jovyan/work \
jupyter/scipy-notebook
トラブルシューティング
よくある問題と解決方法
問題1: ポートがすでに使用されている
# エラー例
docker: Error response from daemon: driver failed programming external connectivity
on endpoint: Bind for 0.0.0.0:8888 failed: port is already allocated.
解決方法
解決法1: 別のポートを使う(最も簡単)
# ホスト側のポートを8889に変更
docker run -p 8889:8888 jupyter/scipy-notebook
# ブラウザでは http://localhost:8889 にアクセス
解決法2: 使用中のコンテナを確認して停止
# 実行中のコンテナを確認
docker ps
# 該当するコンテナを停止
docker stop [CONTAINER_ID or NAME]
解決法3: ポートを使用しているプロセスを確認
# macOS/Linux
lsof -i :8888
# 表示されたPIDを使って停止
kill -9 [PID]
# Windows(PowerShell)
netstat -ano | findstr :8888
# 表示されたPIDを使って停止
taskkill /PID [PID] /F
問題2: ファイルが保存されない
問題3: メモリ不足エラー
# エラー例
MemoryError: Unable to allocate XXX MiB for an array
解決方法
Docker Desktopの設定でメモリ制限を増やす
- Docker Desktopを開く
- 設定アイコン(⚙️)をクリック
- Resources → Memory
- メモリを8GB以上に設定(推奨: 16GB)
- Apply & Restart
コマンドラインで一時的に増やす
docker run -p 8888:8888 --memory="8g" -v $(pwd):/home/jovyan/work jupyter/scipy-notebook
問題4: パーミッションエラー(Permission denied)
Linuxで -v
オプション使用時に発生することがあります。
解決方法
解決法1: ユーザーIDを指定して起動
docker run -p 8888:8888 \
-v $(pwd):/home/jovyan/work \
--user $(id -u):$(id -g) \
jupyter/scipy-notebook
解決法2: ディレクトリの権限を変更
# 作業ディレクトリの権限を変更
chmod -R 777 ./notebooks
問題5: コンテナが起動しない
# ログを確認して原因を特定
docker logs [CONTAINER_NAME]
# コンテナの詳細情報を確認
docker inspect [CONTAINER_NAME]
プロジェクトテンプレート 📁
実際のプロジェクトで使える構成例です。
ディレクトリ構造
my-ml-project/
├── docker-compose.yml # Docker Compose設定
├── Dockerfile # カスタムイメージ定義
├── requirements.txt # Pythonライブラリ一覧
├── .dockerignore # イメージに含めないファイル
├── .gitignore # Gitで管理しないファイル
├── README.md # プロジェクト説明
├── notebooks/ # Jupyterノートブック
│ ├── 01_data_exploration.ipynb
│ ├── 02_preprocessing.ipynb
│ ├── 03_modeling.ipynb
│ └── 04_evaluation.ipynb
├── data/ # データ格納
│ ├── raw/ # 生データ
│ ├── processed/ # 前処理済みデータ
│ └── models/ # 学習済みモデル
├── src/ # Pythonモジュール
│ ├── __init__.py
│ ├── preprocessing.py # 前処理関数
│ ├── models.py # モデル定義
│ └── utils.py # ユーティリティ関数
└── tests/ # テストコード
├── __init__.py
└── test_preprocessing.py
requirements.txt
# データ分析基本ライブラリ
pandas==2.0.3
numpy==1.24.3
# 可視化
matplotlib==3.7.2
seaborn==0.12.2
plotly==5.15.0
# 機械学習
scikit-learn==1.3.0
xgboost==1.7.6
lightgbm==4.0.0
# ディープラーニング(必要に応じてコメントアウト解除)
# tensorflow==2.13.0
# torch==2.0.1
# データベース接続
sqlalchemy==2.0.19
psycopg2-binary==2.9.6
# Jupyter関連
jupyter==1.0.0
jupyterlab==4.0.3
ipywidgets==8.1.0
jupyterlab-git==0.41.0
# その他便利ツール
tqdm==4.65.0
python-dotenv==1.0.0
.dockerignore
- Dockerイメージのビルド時、Dockerデーモンに送るビルドコンテキストから特定のファイルやディレクトリを除外するための設定ファイル
# Pythonキャッシュ
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
# Jupyter
.ipynb_checkpoints/
*.ipynb_checkpoints
# 仮想環境
venv/
env/
ENV/
# Git
.git/
.gitignore
# IDE
.vscode/
.idea/
*.swp
*.swo
# データファイル(大きいファイルは除外)
data/raw/*.csv
data/raw/*.parquet
*.h5
*.pkl
# OS
.DS_Store
Thumbs.db
README.md(サンプル)
# My ML Project
## セットアップ
### 1. リポジトリをクローン
```bash
git clone <repository-url>
cd my-ml-project
2. Docker環境を起動
docker-compose up -d
3. Jupyterにアクセス
ブラウザで http://localhost:8888 を開く
ディレクトリ構成
-
notebooks/
: Jupyterノートブック -
data/
: データファイル -
src/
: Pythonモジュール
開発フロー
-
notebooks/
でデータ探索・分析 - 再利用可能なコードを
src/
にモジュール化 - テストを
tests/
に追加
ベストプラクティス
1️⃣ 軽量なイメージを作る
不要なファイルを除外する
.dockerignore
ファイルを活用して、イメージに含める必要のないファイルを除外しましょう。
# .dockerignore
__pycache__/
*.pyc
.git/
.venv/
*.ipynb_checkpoints/
data/raw/*.csv
*.log
2️⃣ セキュリティの考慮 🛡️
環境変数の安全な管理
# docker-compose.yml
services:
jupyter:
build: .
env_file:
- .env # 機密情報は.envファイルに記載
# .env(.gitignoreに追加すること!)
POSTGRES_PASSWORD=your_secure_password
API_KEY=your_api_key
3️⃣ 定期的なイメージ更新 🔄
セキュリティパッチやバグ修正を適用するため、定期的にベースイメージを更新しましょう。
# 最新のベースイメージを取得
docker pull jupyter/scipy-notebook:latest
# イメージを再ビルド(キャッシュなし)
docker build --no-cache -t my-jupyter .
# 古いイメージを削除してディスク容量を節約
docker image prune -a
更新の推奨頻度
- 開発環境: 月1回程度
- 本番環境: セキュリティアップデートがあれば即時対応
4️⃣ バージョン管理とタグ付け 🏷️
イメージにバージョンタグを付けて管理すると、ロールバックが簡単になります。
# バージョンを指定してビルド
docker build -t my-jupyter:1.0.0 .
docker build -t my-jupyter:latest .
# 特定バージョンを使用
docker run -p 8888:8888 my-jupyter:1.0.0
応用例:チーム開発での活用
ケース1: チーム全員で同じ環境を共有
1. リポジトリにDocker設定を含める
project/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md
2. チームメンバーは以下を実行するだけ
git clone <repository>
cd project
docker-compose up -d
これで全員が同じ環境で開発できます!
ケース2: 複数プロジェクトの環境を切り替え
# プロジェクトAの環境
cd project-a
docker-compose up -d
# プロジェクトBの環境(別のポートで起動)
cd ../project-b
docker-compose up -d
# 両方同時に動かせる(ポートが異なれば)
ケース3: CI/CDパイプラインでの活用
GitHubActionsなどのCI/CDと組み合わせると、ノートブックの自動テストも可能です。
# .github/workflows/test.yml
name: Test Notebooks
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: docker build -t test-jupyter .
- name: Run tests
run: |
docker run --rm test-jupyter \
pytest notebooks/ --nbval
パフォーマンス最適化のTips 🚀
1. イメージビルドの高速化
レイヤーキャッシュを活用
# ❌ 悪い例:requirements.txtが変わらなくてもCOPYが実行される
COPY . /app
RUN pip install -r requirements.txt
# ✅ 良い例:requirements.txtが変わった時だけインストール
COPY requirements.txt /app/
RUN pip install -r requirements.txt
COPY . /app
2. 起動時間の短縮
よく使うライブラリは事前にインポート
# startup.py(起動時に実行)
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
print("✅ Libraries loaded successfully!")
# Dockerfileに追加
COPY startup.py /home/jovyan/.ipython/profile_default/startup/
3. メモリ使用量の最適化
# Jupyter内で大きなデータを扱う際のTips
# 1. データ型を最適化
df = pd.read_csv('large_file.csv')
df = df.astype({
'id': 'int32', # int64 → int32で半分のメモリ
'category': 'category' # objectより効率的
})
# 2. チャンク読み込み
for chunk in pd.read_csv('huge_file.csv', chunksize=10000):
process(chunk)
# 3. 不要な変数を削除
del large_dataframe
import gc
gc.collect()
よくある質問(FAQ)
Q1: Dockerを使うとPCが重くなりませんか?
A: 適切にリソース制限を設定すれば、通常の使用では問題ありません。Docker Desktopの設定で、メモリやCPUの使用量を調整できます。
Q2: Jupyter以外のIDEも使えますか?
A: はい!VS CodeのRemote Containers拡張機能を使えば、同じDocker環境内でVS Codeも使えます。
// .devcontainer/devcontainer.json
{
"name": "Jupyter Environment",
"dockerComposeFile": "../docker-compose.yml",
"service": "jupyter",
"workspaceFolder": "/home/jovyan/work"
}
Q3: GPUなしでもディープラーニングはできますか?
A: CPU版のTensorFlowやPyTorchも使えますが、学習速度は遅くなります。小規模なモデルや学習にはCPUでも十分です。
Q4: 既存のAnaconda環境をDockerに移行できますか?
A: はい。既存の環境をエクスポートして、requirements.txtに変換できます。
# Anaconda環境をエクスポート
conda list --export > conda_requirements.txt
# pip形式に変換(手作業が必要な場合もあり)
conda list --export | grep -v "^#" | cut -d "=" -f 1 > requirements.txt
Q5: コンテナ内のファイルをどうやって取り出せますか?
A: docker cp
コマンドで簡単にコピーできます。
# コンテナからホストへコピー
docker cp my-jupyter:/home/jovyan/work/notebook.ipynb ./
# ホストからコンテナへコピー
docker cp ./data.csv my-jupyter:/home/jovyan/data/
ただし、-v
オプションでマウントしていれば、ファイルは自動的に同期されます。
まとめ
DockerでJupyter環境を構築する3つの方法を紹介しました。
方法 | 難易度 | 用途 | 所要時間 | おすすめ度 |
---|---|---|---|---|
方法1: 最速起動 | ⭐ | お試し・簡単な分析 | 1分 | ⭐⭐⭐ 初心者向け |
方法2: Dockerfile | ⭐⭐ | カスタマイズが必要なプロジェクト | 10分 | ⭐⭐⭐⭐ 実務向け |
方法3: Docker Compose | ⭐⭐⭐ | 複数サービス連携・チーム開発 | 15分 | ⭐⭐⭐⭐⭐ 本格開発向け |
この記事で学んだこと
- ✅ Dockerを使った環境構築の3つの方法
- ✅ ライブラリの追加とカスタマイズ方法
- ✅ Docker Composeを使った複数サービスの管理
- ✅ GPU環境の構築方法
- ✅ セキュリティとベストプラクティス
- ✅ トラブルシューティングの方法
環境構築の悩みから解放されて、本来のデータ分析や機械学習の開発に集中できるようになります!
次のステップ 🚀
この記事を読んだら、ぜひ実際に手を動かしてみてください!
- Docker Desktopをインストール
- 方法1の1行コマンドを実行
- 簡単なデータ分析を試してみる
- 自分のプロジェクトに合わせてカスタマイズ
最後に
最後まで読んでくださり、ありがとうございました!
この記事が少しでも皆さんの学びや気づきにつながれば嬉しいです ✨
ぜひ「いいね」と共有をお願いします!🚀
📬 仕事の相談はこちら 📬
お仕事のご相談やご依頼は、下記のフォームよりお気軽にお問い合わせください。
👉 お問い合わせフォーム
メールでのご連絡をご希望の方は、こちらまでお願いいたします。
📧 info@dotconf.co.jp
⭐ お知らせ ⭐
私たちは AI学習サービス「aipass」 も運営しています。
実践的なAIプログラミング学習や副業案件獲得支援をお届けしていますので、ぜひこちらもご覧ください!
Discussion