🕌

依存管理の発展（Poetry / pip-tools / uv）— ロック、再現、配布まで

に公開
AI
ai入門
tech

環境は動いた。次は**「同じ環境をいつでも、誰でも、どこでも再現」する番。
この記事では、requirements.txtだけに頼らない3つの選択肢**——Poetry / pip-tools / uv——を、最小レシピ→運用の型→チーム配布の流れでまとめる。
ゴールは、開発は快適に、CI/本番は厳密にを両立させること。

TL;DR（結論から）

  • Poetry：pyproject.tomlに依存・メタ情報を一元管理。ライブラリ配布やスクリプト定義まで含めて“全部のる”。

  • pip-tools：requirements.in → requirements.txt をコンパイルして厳密ロック。今あるpip文化を崩さず堅牢化。

  • uv：超高速なpip/venv互換ツール。pip-tools互換のcompile/syncも持ち、速度最優先の現場に強い。

  • 使い分け：

    • アプリ開発で軽量・既存資産重視 → pip-tools / uv
    • パッケージ配布や一元管理を重視 → Poetry
    • 速度重視・モダン運用 → uv

なぜ強化するのか（背景）

  • “開発機では動く”を再現性で終わらせる（ロック/ハッシュ/同期）。
  • “更新したら壊れた”を差分更新で止める（compile→sync）。
  • Docker/CI/WSL/異アーキでも同じビルドを出す（固定ファイルとハッシュ検証）。

1) Poetry — ぜんぶpyproject.tomlで管理する派

使いどころ

  • 依存・スクリプト・ビルド設定まで一枚の定義で持ちたい。
  • 将来パッケージ配布（build/publish）の可能性がある。

最小レシピ

# 1. インストール（どれか・例）
pipx install poetry

# 2. 初期化（既存プロジェクトならそのディレクトリで）
poetry init   # 対話で依存定義 → pyproject.toml 生成

# 3. 依存追加
poetry add flask
poetry add --group dev black ruff pytest

# 4. インストール & 実行（Poetry管理のvenv内）
poetry install
poetry run python -V

スクリプト定義（便利）

# pyproject.toml
[tool.poetry.scripts]
start = "app.__main__:main"

poetry run start

Docker/CIへの“受け渡し”（requirements化）

# 本番用に requirements.txt を吐き出す
poetry export -f requirements.txt --output requirements.txt --with-hashes
# そのrequirementsでpipインストール（Dockerfile/CI）
python -m pip install --require-hashes -r requirements.txt

小ネタ

  • プロジェクト内にvenvを作りたい：poetry config virtualenvs.in-project true
  • Pythonの切替：poetry env use 3.11

2) pip-tools — 既存のpip文化を“堅牢”にする派

使いどころ

  • いまのvenv + pip + requirements文化は保ちたいが、ロックを厳密にしたい。
  • 依存の**ソース（.in）とロック結果（.txt）**を分けたい。

最小レシピ

python -m pip install -U pip setuptools wheel
python -m pip install pip-tools

# requirements.in（人が書く元）
flask
uvicorn

# requirements-dev.in（開発用）
-r requirements.txt
black
ruff
pytest

# ロック（ハッシュ付きで厳密化）
pip-compile --generate-hashes -o requirements.txt requirements.in
pip-compile --generate-hashes -o requirements-dev.txt requirements-dev.in

# 同期（環境をロック内容にぴったり合わせる）
pip-sync requirements.txt requirements-dev.txt
  • “本番は最小だけ”：pip-sync requirements.txt
  • “開発は追加で”：pip-sync requirements.txt requirements-dev.txt

さらに一歩（constraintsの活用）

  • アプリA/Bで共有する上限制約は constraints.txt に分離。
  • 例：pip install -r requirements.txt -c constraints.txt

3) uv — 超高速pip/venv互換 + compile/syncで快適運用

使いどころ

  • 速度が命（CIが遅い/手元のpipが遅い）。
  • pip-toolsと同様のcompile/sync運用を高速化したい。
  • 既存のrequirements運用を崩したくない。

最小レシピ

# 1. インストール（例：pipx推奨）
pipx install uv

# 2. 仮想環境を作る
uv venv        # .venv を生成（なければ）

# 3. インストール（pip互換）
uv pip install -r requirements.txt

# 4. ぴったり同期（pip-toolsのsync相当）
uv pip sync requirements.txt

# 5. reqをコンパイル（pip-toolsのcompile相当）
uv pip compile requirements.in -o requirements.txt --generate-hashes
  • 実行も高速に：uv run python app.py（正しいvenvで即起動）
  • 既存のpip/pip-tools運用をほぼ置き換えられるのが強み。

チーム運用の型（共通ベストプラクティス）

  • 開発と本番を分離：

    • requirements.in / requirements-dev.in（pip-tools/uv）
    • Poetryならgroup（--group dev）で明示。

  • ハッシュ検証を有効化：

    • --generate-hashes でロック、--require-hashes で厳密インストール。

  • Dockerは“固定ファイル→インストール→COPY”の順：

    • 依存が変わらなければビルドキャッシュが効く。

  • .env と .env.example を必ず用意（機密はコミットしない）。

  • CIはcompile→差分検知→syncの流れをジョブ化。

  • アーキの差（arm64/amd64）はランタイム依存に影響することがある（特にネイティブ拡張）。

    • 可能なら同アーキでロック→同アーキでビルド。

選び方ガイド（文章チャート）

  • 一枚の定義で“全部管理”＆将来配布も視野 → Poetry
  • 既存pip文化で堅牢化／差分更新が欲しい → pip-tools
  • 速度最優先・CI短縮・互換性確保 → uv（pip-tools代替にも）

迷ったら：アプリ開発で軽量に回すなら pip-tools or uv、ライブラリ配布やメタ情報統合まで狙うなら Poetry。

失敗しがちなポイント（アンチパターン）

  • pip freeze を配布用requirementsにそのまま採用（不要依存混入）。
  • Poetryでexportを忘れてDocker本番にpoetry installだけ入れる（キャッシュ効かない・再現がブレやすい）。
  • sync を使わず install -U を連打（ロック破りになりがち）。
  • 異アーキ/異OSで同じロックを絶対視（ネイティブ依存で崩れる例あり）。

すぐ使えるテンプレ（コピー用）

pip-tools（開発＋本番）

python -m pip install -U pip setuptools wheel pip-tools
pip-compile --generate-hashes -o requirements.txt requirements.in
pip-compile --generate-hashes -o requirements-dev.txt requirements-dev.in
pip-sync requirements.txt requirements-dev.txt

Poetry → 本番requirementsへ輸出

poetry export -f requirements.txt --output requirements.txt --with-hashes
python -m pip install --require-hashes -r requirements.txt

uv（compile/sync置き換え）

pipx install uv
uv venv
uv pip compile requirements.in -o requirements.txt --generate-hashes
uv pip sync requirements.txt

まとめ

  • Poetry＝一元管理・配布まで視野。
  • pip-tools＝既存文化のまま“厳密ロック”。
  • uv＝pip/venv互換を超高速で回す。
  • どれを選んでも、ロック→同期→配布の型を確立すれば“再現できる開発”は完成する。

Discussion