DevContainerとuvで構築する爆速Python開発環境｜VS Codeセットアップ手順

1 はじめに：なぜDevContainerとuvの組み合わせなのか
- 1.1 使用する技術スタック
2 DevContainer + uv環境の全体構成
3 ステップ1: Microsoft公式イメージベースのDockerfile
4 ステップ2: Docker Composeでコンテナ定義
5 ステップ3: DevContainer設定
6 ステップ4: VS CodeでDevContainerを起動して開発開始
- 6.1 1. プロジェクトをDevContainerで開く
- 6.2 2. ターミナルを開いて確認
7 ステップ5: uvでプロジェクト初期化
- 7.1 pyproject.tomlの例
- 7.2 セットアップの確認
8 動作確認：DevContainerでFastAPIアプリを構築
9 DevContainer + uv環境でよくあるエラーと解決法
10 まとめ
- 10.1 この環境で得られる3つのメリット
11 参考リンク

はじめに：なぜDevContainerとuvの組み合わせなのか

ども！新卒のスムーズな開発のために環境を作っていたりする龍ちゃんです。直近でPythonのDevContainer環境を作る機会がありまして、今までpipで環境を作っていました。どうせなら、モダンな環境で作り直して渡そうと考えていました。モダンなPython開発環境に求められる要素は何でしょうか？

再現可能な環境: チーム全員が同じ環境で開発できる
高速なパッケージ管理: ストレスのない依存関係のインストール
拡張性: 必要に応じてツールを追加できる柔軟性

本記事では、DevContainerとuvを使った高速で再現可能なPython開発環境の構築方法を、ステップバイステップで解説します。

使用する技術スタック

DevContainer: VS Codeの開発コンテナ機能
uv: Rustで実装された高速Pythonパッケージマネージャー（pipの10-100倍速）
Microsoft公式イメージ: 安定性と互換性が保証された基盤

DevContainer + uv環境の全体構成

今回構築する環境のディレクトリ構成は以下の通りです：

project-root/
├── .devcontainer/
│   ├── Dockerfile          # Python + Node.js環境の定義
│   ├── compose.yml         # Dockerコンテナの設定
│   └── devcontainer.json   # VS Code DevContainer設定
├── pyproject.toml          # Pythonプロジェクト設定
├── src/                    # ソースコード
└── tests/                  # テストコード

ステップ1: Microsoft公式イメージベースのDockerfile

Python環境にuvを追加したシンプルなDockerfileを作成します。

# .devcontainer/Dockerfile

# Microsoft公式のPython DevContainerイメージを使用
FROM mcr.microsoft.com/devcontainers/python:3.11

# 追加ツール（必要に応じて）
USER vscode
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/home/vscode/.local/bin:${PATH}"

# 作業ディレクトリの設定
WORKDIR /home/vscode/python

# コンテナを起動したままにする
CMD ["sleep", "infinity"]

ポイント:

Microsoft公式イメージで安定性を担保
非rootユーザー（vscode）で安全に実行
uv事前インストールで初回から高速セットアップ

ステップ2: Docker Composeでコンテナ定義

# .devcontainer/compose.yml
services:
  python:
    build:
      context: .
      dockerfile: ./Dockerfile
    tty: true
    volumes:
      - type: bind
        source: ../
        target: /home/vscode/python
    restart: unless-stopped
    # ports:
    #   - "8000:8000"  # FastAPI等のWebアプリ用

ポイント:

単一サービス構成でシンプル
ボリュームマウントでホストと同期

ステップ3: DevContainer設定

// .devcontainer/devcontainer.json
{
  "name": "uv-python",
  "service": "python",
  "dockerComposeFile": "./compose.yml",
  "workspaceFolder": "/home/vscode/python",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "ms-python.black-formatter"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/home/vscode/python/.venv/bin/python",
        "python.testing.pytestEnabled": true,
        "python.testing.pytestArgs": ["-q"],
        "editor.formatOnSave": true,
        "python.formatting.provider": "black"
      }
    }
  }
}

ステップ4: VS CodeでDevContainerを起動して開発開始

1. プロジェクトをDevContainerで開く

VS Codeでプロジェクトディレクトリを開く
コマンドパレット（Cmd/Ctrl + Shift + P）を開く
「Dev Containers: Reopen in Container」 を選択
初回起動時はDockerイメージのビルドに数分かかります

コンテナが起動すると、VS Codeのウィンドウ左下に「Dev Container: uv-python」と表示されます。

2. ターミナルを開いて確認

VS Codeのターミナルを開き、環境を確認します。

# Pythonのバージョン確認
python --version

# uvが利用可能か確認
uv --version

# 作業ディレクトリの確認
pwd  # /home/vscode/python が表示されるはず

ステップ5: uvでプロジェクト初期化

# プロジェクトの初期化（pyproject.toml生成）
uv init

# 仮想環境の作成と有効化
uv venv
source .venv/bin/activate

# 依存関係の追加
uv add fastapi uvicorn pydantic
uv add --dev pytest black flake8 mypy httpx

# 反映
uv sync --all-groups

pyproject.tomlの例

[project]
name = "python"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
  "fastapi>=0.120.1",
  "pydantic>=2.12.3",
  "uvicorn>=0.38.0",
]

[dependency-groups]
dev = [
  "black>=25.9.0",
  "flake8>=7.3.0",
  "httpx>=0.28.1",
  "mypy>=1.18.2",
  "pytest>=8.4.2",
]

[tool.black]
line-length = 100
target-version = ['py311']

[tool.mypy]
python_version = "3.11"
strict = true
ignore_missing_imports = true

[tool.flake8]
max-line-length = 100
extend-ignore = ["E203", "W503"]

[tool.pytest.ini_options]

注意:
[dependency-groups]は比較的新しい機能です。古いツールとの互換性が必要な場合は、代わりに[project.optional-dependencies]を使用することもできますが、uvを使う場合は[dependency-groups]の使用が推奨されます。

セットアップの確認

最後に、セットアップが正しく完了したことを確認します。

# インストールされたパッケージの確認
uv pip list

# Blackでフォーマットが動作するか確認
black --version

# mypyで型チェックが動作するか確認
mypy --version

# pytestが動作するか確認
pytest --version

動作確認：DevContainerでFastAPIアプリを構築

簡単なアプリケーションの作成

セットアップが完了したら、実際にコードを書いて動作確認してみましょう。

# src/main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, uv DevContainer!"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

アプリケーションの実行

# FastAPIアプリケーションの起動
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

ブラウザで http://localhost:8000 にアクセスすると、動作確認できます。

フォーマットとLintの実行

保存時の自動フォーマットに加えて、手動でも実行できます。

# Blackでコードをフォーマット
black src/

# Flake8でLintチェック
flake8 src/

# mypyで型チェック
mypy src/

# すべてをまとめて実行
black src/ && flake8 src/ && mypy src/

テストの作成と実行

# tests/test_main.py
from fastapi.testclient import TestClient
from src.main import app

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, uv DevContainer!"}

# テストの実行
uv run pytest

# カバレッジ付きでテスト実行
uv run pytest --cov=src tests/

uvコマンドのクイックリファレンス

開発中によく使うuvコマンドをまとめました。

# パッケージの追加
uv add requests               # 通常の依存関係
uv add --dev pytest-cov       # 開発用依存関係

# パッケージの削除
uv remove requests            # パッケージの削除

# 依存関係の更新
uv lock                       # ロックファイルの更新
uv sync                       # 依存関係の同期

# pip互換コマンド
uv pip install requests       # pipコマンドと同じように使える
uv pip list                   # インストール済みパッケージ一覧
uv pip freeze                 # requirements.txt形式で出力

# 仮想環境の管理
uv venv                       # 仮想環境の作成
uv venv .venv --python 3.11   # Pythonバージョン指定

# requirements.txtとの連携
uv pip install -r requirements.txt  # requirements.txtからインストール
uv pip freeze > requirements.txt    # requirements.txtの生成

DevContainer + uv環境でよくあるエラーと解決法

問題1: uvコマンドが見つからない

# PATHを確認
echo $PATH

# PATHに追加（必要な場合）
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# uvの再インストール
curl -LsSf https://astral.sh/uv/install.sh | sh

問題2: Pythonインタープリターが認識されない

VS Codeのコマンドパレットから 「Python: Select Interpreter」 を選択し、/home/vscode/python/.venv/bin/python を指定します。

または、devcontainer.jsonで指定されているパスを確認：

"python.defaultInterpreterPath": "/home/vscode/python/.venv/bin/python"

問題3: パーミッションエラーが発生する

# 現在のユーザーを確認
whoami  # vscode であることを確認

# ディレクトリの所有者を確認
ls -la /home/vscode/python

# 必要に応じて権限を修正
sudo chown -R vscode:vscode /home/vscode/python

問題4: pytestがsrcをモジュールとして認識せず import に失敗する

症状:
from src.main import app で ModuleNotFoundError などの収集時エラー
原因:
Python パスにプロジェクトルート（.）が含まれず、src がモジュール解決できない
対処:
- pyproject.toml に Python パスを付与（推奨） [tool.pytest.ini_options] pythonpath = ["."]
- 併用可: src/__init__.py を追加（空でOK）
検証:
uv run pytest -q が成功すること。python -c "import sys; print(sys.path[0])" でルートが入っていることを確認

まとめ

今回は、DevContainerとuvを組み合わせた爆速Python開発環境の構築方法を見てきました。

この環境で得られる3つのメリット

✅ 圧倒的な速度: uvによってpipの10-100倍速でパッケージ管理

✅ 完全な再現性: Dockerでチーム全員が同じ環境を共有

✅ VS Code統合: 拡張機能やデバッグがそのまま使える

特に、「ローカル環境を汚したくない」「チーム開発で環境差異に悩んでいる」という方には、ぜひ試していただきたいセットアップです。

実際にこの環境を使うことで、環境構築のストレスから解放され、コーディングに集中できるようになります。セットアップは最初の1回だけ。あとはチーム全員が同じ環境で快適に開発できますよ。

皆さんも、ぜひDevContainer × uv環境でPython開発にチャレンジしてみてください！質問や感想は、コメント欄でお待ちしております。

もしこの環境でNodeを使いたい（Claude CodeやCodexなどのnpmでインストールする系のツール）を使う場合は、こちらを参考にしてください。

参考リンク

ご覧いただきありがとうございます！この投稿はお役に立ちましたか？

役に立った役に立たなかった

0人がこの投稿は役に立ったと言っています。