概要（pip freezeは「今の環境を丸ごと再現するためのスナップショット」）
pip freezeは、現在のPython環境に入っているライブラリをname==version形式で完全に列挙します。これをrequirements.txtに保存し、他環境で一括インストールすれば「同じ状態」を再現できます。重要なのは、仮想環境で実行すること、固定化→復元の型を守ること、freezeとlistの目的の違い、そして更新時の検証（壊さず上げる手順）です。
固定化と復元の基本（仮想環境が前提）
仮想環境での固定化（スナップショットを取る）
# 仮想環境を作って有効化
python -m venv venv
source venv/bin/activate # Windowsは venv\Scripts\Activate.ps1
# スナップショットを書き出し
python -m pip freeze > requirements.txt
ねらい: 意図した環境（venv）だけを固定します。グローバル環境を誤って固定すると再現性が崩れます。
別環境での復元（一括インストール）
python -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
結果: requirements.txtのバージョンでピン止めされた同一セットが再現されます。
インタープリタ確認（取り違え防止の一手）
python -c "import sys; print(sys.executable)"
python -m pip --version
ねらい: “今のPython”とpipの紐付けを確認し、誤環境でfreeze/restoreしないようにします.
freezeとlistの違い（役割の線引きを守る）
目的の違いと正しい使い分け
- pip freeze: 再現用の完全固定（依存も含む全てをname==versionで保存）。
- pip list: 現状把握（目視確認や更新候補の洗い出しに便利）。固定には使わない。
# 固定と復元
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
# 現状確認・更新候補
python -m pip list
python -m pip list --outdated
要点: “保存・再現”はfreeze、“確認・検討”はlistで分業します。
実務で効く深掘り（最小化・範囲指定・安全更新）
不要依存を避ける「最小のrequirements」も併用
freezeは“入っている全部”を出すため、試しに入れたものまで混ざりやすいです。本番向けは「上位パッケージだけ」を手書きで管理し、CIや検証ではfreezeの完全スナップショットを使うのが現実的です。
# requirements.txt（最小例：上位のみ）
requests==2.31.0
python-dotenv==1.0.1
効果: 冗長な依存を持ち込まず、脆弱性調査や更新がシンプルになります。
範囲指定で安全余地を持たせる（検証→固定し直し）
# 検証用に範囲で更新してテスト
python -m pip install "httpx>=0.27,<0.28" "pydantic~=2.9"
pytest -q
# 合格したら固定に戻す
python -m pip freeze > requirements.txt
ねらい: 一時的に範囲で更新→テスト合格後にピン止めへ、という二段運用で壊れにくくします。
安全なアップデートの型（新規venvで検証）
python -m venv venv-up && source venv-up/bin/activate
python -m pip install -r requirements.txt --upgrade
pytest -q # 動作確認
python -m pip freeze > requirements.txt # 固定し直し
理由: 既存環境を触らず検証し、問題ないと判断してから本線に反映します。
応用トピック（constraints・ハッシュチェック・環境分割）
constraints.txtで「下位依存だけ固定」する
上位は最小のrequirements、下位（間接依存）はconstraintsで固定すると、柔軟性と再現性を両立できます。
# requirements.txt（上位だけ）
fastapi==0.115.0
# constraints.txt（下位を固定）
pydantic==2.9.2
python -m pip install -r requirements.txt -c constraints.txt
効果: コアは固定しつつ、直接依存の更新余地も確保できます。
–require-hashesで「完全検証付き」インストール
requirements.txtに各行のハッシュを入れ、チェック付きでインストールします（セキュリティが上がる反面、運用は厳密に）。
# 例（概念）
requests==2.31.0 \
--hash=sha256:XXXXXXXXXXXXXXXX \
--hash=sha256:YYYYYYYYYYYYYYYY
python -m pip install --require-hashes -r requirements.txt
``]
**ねらい:** 取得物の改ざん検知。配布パスが変わるとハッシュを更新する必要があります。
### 環境別ファイルで分離（開発・テスト・本番）
```text
# requirements.txt（基本）
httpx==0.27.0
pydantic==2.9.2
# requirements-dev.txt（補助）
pytest==8.3.3
black==24.10.0
mypy==1.12.0
python -m pip install -r requirements.txt -r requirements-dev.txt
効果: 本番に開発ツールを持ち込まず、環境ごとに管理が透明になります。
よくあるつまずきと対処（競合・ビルド・誤環境）
依存競合で失敗する
症状: “Conflicting dependencies” が出る
対処: 範囲指定の見直し、上位のバージョンを揃える、更新を小分けに進めて原因を特定する。
C拡張ビルドでエラー
症状: numpy/lxml 等のビルド失敗
対処: 事前ビルドホイールがあるPython/OS組み合わせを選ぶ、必要な開発ツールやヘッダを導入する。
グローバル環境をfreezeしてしまう
対処: 必ずvenvを有効化してから python -m pip freeze。プロンプトの(venv)表示とsys.executableのパスで確認します。
VCS/ローカルのeditableが混ざる
症状: -e . や git+URL が入っていると環境差が出る
対処: チーム合意の固定法に統一（タグ指定のGit依存、wheel配布、editableを本番から除外）します。
例題（Web/APIプロジェクトの現実的ワークフロー）
例題1：最小導入→動作確認→freezeで共有
mkdir myapi && cd myapi
python -m venv venv && source venv/bin/activate
python -m pip install requests python-dotenv
python - <<'PY'
import requests, dotenv
print("requests:", requests.__version__, "dotenv:", dotenv.__version__)
PY
python -m pip freeze > requirements.txt
効果: “install -r requirements.txt”だけで、チームやCIが同じ環境へ。
例題2：ズレ検知（現状vsファイル）
import json, subprocess, pathlib
curr = json.loads(subprocess.check_output(["python", "-m", "pip", "list", "--format=json"], text=True))
curr_map = {p["name"].lower(): p["version"] for p in curr}
reqs = {}
for line in pathlib.Path("requirements.txt").read_text(encoding="utf-8").splitlines():
line = line.strip()
if not line or line.startswith("#") or "==" not in line:
continue
name, ver = line.split("==", 1)
reqs[name.lower()] = ver
missing = sorted(set(reqs) - set(curr_map))
diff = {n: (curr_map.get(n), reqs[n]) for n in reqs if curr_map.get(n) and curr_map[n] != reqs[n]}
print("Missing:", missing)
print("Version diff:", diff)
効果: 何が足りないか、どれがバージョン不一致かを即座に把握できます。
例題3：constraintsで下位依存を固定
# requirements.txt
fastapi==0.115.0
# constraints.txt
pydantic==2.9.2
python -m pip install -r requirements.txt -c constraints.txt
効果: 直接依存の更新余地を保ちつつ、下位依存は固定できます。
まとめ（pip freezeは再現性の中核。型で運用すれば壊れない）
pip freezeは「いまの環境を完全記録」し、requirements.txtから「どこでも同じ状態」を復元するための中核です。仮想環境で実行し、固定化→検証→固定し直しの型を徹底する。freezeは保存・再現、listは確認・検討、と役割を分ける。必要に応じて最小のrequirements、constraints、ハッシュ検証、環境分割を使い、アップデートは新規venvでテストしてから反映する。これを体に入れれば、初心者でも短い手順で「壊れない・再現できる・共有しやすい」依存管理が実現します。