pip-toolsとは requirements.txt運用を堅牢にする補助具

2026年6月3日

pip-toolsはJazzbandコミュニティが2015年頃から保守しているPython向けのrequirementsコンパイラ群で、requirements.inに書かれた緩い指定からハッシュ込みのrequirements.txtを生成するpip-compileと、実環境を要求通りに同期させるpip-syncを提供する。pipやvenvを置き換えるのではなく補完するスタンスで、企業の本番運用に深く根付いてきた。本稿ではpip-toolsの設計思想、使い方、Poetryやuvとのワークフローの違い、運用上の勘所を整理する。

この記事の目次

pip-toolsが解決する課題
pip-compileのオプションと運用
pip-syncを用いた本番運用
現代ツールとの併存
まとめ

pip-toolsが解決する課題

pip-toolsの中心思想は「人間が編集するファイル」と「機械が生成するファイル」を厳密に分けることにある。requirements.in にプロジェクトが直接必要とするライブラリと緩い制約を書き、pip-compile を実行するとrequirements.txt に推移的依存を含む完全固定リストが生成される。生成物にはどのパッケージがどのパッケージから来たのか注釈が付くため、依存ツリーの構造が一目でわかる。

pip-sync はrequirements.txt と実環境を比較し、不足分をインストール、余剰分をアンインストールする。pip install -r とは異なり、過去にインストールされた余計なパッケージを掃除してくれる点が運用上大きな差となる。本番イメージで意図しない依存が残ることを防ぐため、CIで pip-sync を使う構成は依然として広く採用されている。PEP 517以降のpyproject.toml中心の世界でも、pip-toolsはpyproject.tomlを入力として扱えるためモダン化への移行も容易だ。

pip-compileのオプションと運用

pip-compileは入力としてrequirements.inかpyproject.tomlを受け取り、pip互換の固定ファイルを出力する。--generate-hashesを付ければSHA256付きのrequirementsとなり、本番でのサプライチェーン保護に活用できる。--upgrade-packageで特定パッケージだけを更新できる点は、セキュリティパッチ適用時に特に重宝する。全体--upgradeで動作確認したあと、影響範囲を最小にしてリリースするフローが定着している。

pyproject.tomlを入力にする場合、[project.dependencies] と [project.optional-dependencies] を直接読み込み、--extra dev で開発用extraを含めて解決できる。出力先を分けることで、本番用とテスト用のrequirementsを別ファイルとしてgit管理する運用が一般的だ。またprivateインデックスを使う場合は --index-url や --extra-index-url を指定し、得られたrequirementsにそれが反映されるため、CIで同じインデックスを参照していれば再現性が保たれる。

pip-syncを用いた本番運用

本番運用ではpip-syncが鍵となる。pip install -rは指定パッケージをインストールするのみで、過去に存在した余剰パッケージは残してしまうが、pip-syncは差分を判定し、余分なものはアンインストールしてしまう。これによりブルーグリーンデプロイやコンテナのlong-running利用でも、長期的な汚染を防げる。

CIでの活用としては、PRごとに pip-compile を再実行し、生成されたrequirements.txt が変わっていないかを git diff で検証する手法がある。意図せず推移的依存が更新された場合に気付くことができ、SLSAやSBOMと組み合わせると監査ログとしても機能する。Docker環境ではpip-sync --pip-args='--no-cache-dir' を使ってキャッシュなしで厳密に再現する運用が広く行われている。GitHub ActionsやGitLab CIでもsetup-python + pip-toolsの組み合わせは依然として一般的だ。

現代ツールとの併存

PoetryやuvがCLIに依存解決を含むのに対し、pip-toolsはユーティリティに徹する設計で外部依存が少なく、CIランナーに導入しやすい。Astral社のuvは「uv pip compile」というpip-tools互換コマンドを提供しており、Rust実装で大幅に高速化された出力は同じ形式となる。段階的にuvへ移行するチームも、pip-toolsの構成をそのまま生かして「コンパイラだけ差し替える」運用ができるため、移行コストが小さい。

Poetryユーザがpip-toolsの仕組みを使いたい場合は poetry export -f requirements.txt が利用できるが、Poetryのロックとは別系統のため運用が二重化する。そのため、pip-tools中心のチームはPoetryに完全移行するよりも、必要に応じてuvに置き換える戦略を取ることが多い。GitHub のJazzbandコミュニティはpip-toolsを集合的に保守しており、メンテナンスも継続的に行われている。