概要（requirements.txtは「同じ環境を誰でも瞬時に再現するための依存リスト」）
requirements.txtは、そのプロジェクトで使う外部ライブラリ名とバージョンを列挙したテキストファイルです。目的は再現性の確保と衝突回避で、仮想環境とセットで使うと「どこでも同じ環境」が素早く作れます。重要なのは、作り方（固定化の仕方）、使い方（インストールコマンド）、バージョン指定のルール、更新運用（freezeの再生成と差分管理）です。
基本の使い方（作成→固定→共有→再現）
最短ルート（仮想環境で依存固定）
- 仮想環境を作って有効化します。
- 必要なライブラリをインストールします。
- 現在の環境をrequirements.txtに書き出します。
- 他環境ではそのファイルからまとめてインストールします。
# 1) 仮想環境
python -m venv venv
source venv/bin/activate # Windowsは venv\Scripts\Activate.ps1
# 2) 依存導入（例）
pip install requests python-dotenv
# 3) 固定化（書き出し）
pip freeze > requirements.txt
# 4) 再現（別環境で）
pip install -r requirements.txt
手書きで最小に保つ（不要依存を避ける）
pip freezeは「今入っているすべて」を出力します。開発中に試したライブラリまで入ることがあり、肥大化しがちです。本当に使うものだけを手書きで管理すると、無駄な依存を避けられます。
# requirements.txt（最小例）
requests==2.31.0
python-dotenv==1.0.1
バージョン指定の深掘り（壊れない範囲を上手に切る）
代表的な指定方法と意味
- 固定（==）：完全一致。再現性が最大だが更新に弱い。
- 下限（>=）：最低バージョンのみ保証。再現性が低く、破壊的変更のリスクあり。
- 範囲（>=, <）：安全余地を確保しつつ更新可能にする現実的な選択。
- 互換（~=）：同一マイナー内で更新を許容（例：2.31系の最新）。
# 例：互換性重視の範囲指定
requests>=2.31,<2.33
python-dotenv~=1.0
実務指針（本番と開発でルールを分ける）
- 本番向け：==で固定、定期的に検証してまとめて上げる。
- 開発向け：範囲指定（>=,< または ~=）でセキュリティ修正を取り込みやすくする。
- ランタイムに影響するコア依存（フレームワークやドライバ）は厳しめ、補助ライブラリは緩めが現実的です。
複数ファイルと環境別運用（開発・本番・テストを分離）
分割して綺麗に管理する
- requirements.txt：アプリの最小セット。
- requirements-dev.txt：開発補助（pytest、black、mypyなど）。
- requirements-prod.txt：本番固定（ピン止め版）。
# 本番
pip install -r requirements-prod.txt
# 開発
pip install -r requirements.txt -r requirements-dev.txt
追加の書き方（プラットフォーム条件やGit参照）
- 条件付き（OS別やPythonバージョン別）: requests==2.31.0; python_version >= “3.9”
- Gitリポジトリから直接インストール: git+https://github.com/user/project.git@v1.2.3
更新とメンテナンス（壊さず上げるための型）
安全なアップデート手順
- 新しい仮想環境を作る（汚染防止）。
- 範囲指定でアップグレードし、テストを実行。
- 合格したらfreezeで新しいrequirements.txtを生成。
- Pull Requestで差分レビュー（何が上がったかを確認）。
python -m venv venv-up
source venv-up/bin/activate
pip install -r requirements.txt --upgrade
pytest -q
pip freeze > requirements.txt
依存の監査と縮小
- 実際にimportしているかを確認して不要を削除。
- 大規模アップデートは小分けに進め、変更点をログに残す。
- セキュリティアラート（脆弱性）に該当する依存は優先的に更新。
よくあるつまずきと対処（競合・ビルド・OS差）
バージョン競合
異なる依存が同じサブ依存の別バージョンを要求して失敗することがあります。メッセージに「Conflicting dependencies」と出た場合は、上位の指定を調整するか、範囲を広げて解決可能な組み合わせに寄せます。
ビルドに失敗（C拡張が必要）
numpyやlxmlなどビルドが必要なライブラリは、OSに開発ツールやヘッダがないとインストールに失敗します。解決策は「事前にビルド環境を整える」か「事前ビルド済みホイールがあるPython/OSバージョンを選ぶ」ことです。
OSごとの差異
LinuxとWindowsで依存の組み合わせが微妙に変わることがあります。環境ごとにrequirementsを分ける、または条件付き指定（platform_systemやpython_version）で調整すると事故を減らせます。
例題（Web/APIプロジェクトでの実用パターン）
例題1：最小固定＋開発拡張
# requirements.txt（最小）
requests==2.31.0
python-dotenv==1.0.1
# requirements-dev.txt（開発補助）
pytest==8.3.3
black==24.10.0
mypy==1.12.0
pip install -r requirements.txt -r requirements-dev.txt
例題2：範囲指定で安全に更新
# requirements.txt（範囲指定）
httpx>=0.27,<0.28
pydantic~=2.9
pip install -r requirements.txt --upgrade
pytest -q
例題3：Git依存と条件付き
# バージョンタグ指定のGit依存
git+https://github.com/encode/httpx.git@0.27.0
# Python 3.11以上のみインストール
uvicorn==0.30.0; python_version >= "3.11"
まとめ（requirements.txtは「再現性」を守る中核）
requirements.txtの核心は、他者・他環境で同一の依存セットを再現できることです。仮想環境での作成・固定化・共有・再現の型を守り、バージョンは「本番は固定、開発は範囲」で運用する。環境別ファイルの分離、条件付き指定やGit参照の活用、アップデート時の検証手順を徹底すれば、初心者でも短い手順で「壊れない・再現できる」依存管理が実現します。