[AI基礎解説]pipってなんだ？— パッケージ管理の全体像と“やってはいけない”集（保存版）
ねらい：Pythonのパッケージ管理を“事故らず速く”回すための実務ガイド。
対象：AI/データ分析/WEBの初〜中級者、チーム開発を視野に入れたい個人。
ゴール：どのPythonに、何を、どう固定して入れるかを一発で説明・実践できる。
TL;DR（最重要3原則）
python -m pipで実行する（入る先のPythonを明示）
仮想環境の外で pip install しない（環境汚染の温床）
依存はファイルで固定（requirements.txt / constraints.txt / できればハッシュ）
pipの役割と用語（最短理解）
pip：Pythonパッケージのインストーラ。site-packages にライブラリを配置する。
pip / pip3 の違い：環境によっては別のPythonに結びつくことがある（罠）。
正解コマンド：常に python -m pip ... を使い、そのシェルで動いているPythonのpipを使う。
# どのPythonに入るかを可視化
python -c "import sys;print(sys.executable)"
python -m pip --version
# 例：macOS/Linux
python3 -m pip install <pkg>
# 例：Windows（pyランチャー）
py -3 -m pip install <pkg>
venv / conda と pip の関係（原則）
venv
軽量で標準。python -m venv .venv → 有効化してから python -m pip install ...。
プロジェクトごとに新しい環境を作る（使い捨て文化）。
conda
OSライブラリも巻き取れる“重戦車”。conda activate 中で pip を使うのはOK。
base 環境に直接インストール多用は非推奨（崩れやすい）。
指針
小規模/軽量：venv
科学計算/依存が重い：conda
どちらでも、python -m pip と プロジェクト単位の環境が基本。
依存を固定する：requirements / constraints / pip-tools
requirements.txt：インストールしたい“完成リスト”（ピン留め済み）。
constraints.txt：バージョンの範囲や上限制約を記載（解決結果のブレ防止）。
運用のコツ
開発者は requirements.in（人が書く元） を管理 → pip-tools で requirements.txt（固定） を生成。
pip freeze > requirements.txt は今の環境全部を固定してしまいがち（不要依存混入）。配布用には非推奨。
例（概念）：
# requirements.in（人が書く元）
flask
uvicorn
# constraints.txt（範囲や上限）
werkzeug>=3.0,<4.0
click<9.0
# requirements.txt（配布・CI用：固定済み）
flask==3.0.3
uvicorn==0.32.0
werkzeug==3.0.4
click==8.1.7
よく使う pip オプション（実務で効く最小セット）
インストール
python -m pip install <pkg>
python -m pip install -r requirements.txt
アップデート
python -m pip list -o（上がっているものを確認）
python -m pip install -U <pkg>（ピンポイント更新）
ミラー/社内レジストリ
--index-url https://<mirror>/simple --trusted-host <mirror>
--extra-index-url https://<extra>/simple
解決方針
--upgrade-strategy only-if-needed（必要最小限）
--upgrade-strategy eager（依存ごと一気に更新）
速度・オフライン対応
事前ダウンロード → オフラインインストール
python -m pip download -r requirements.txt -d vendor/wheels
python -m pip install --no-index --find-links vendor/wheels -r requirements.txt
キャッシュ
python -m pip cache dir（場所）
python -m pip cache purge（掃除）
CLI系ツールは pipx で隔離
狙い：black / ruff / pre-commit など、プロジェクト依存に絡めたくない開発者ツールを独立環境で管理。
導入例（macOS/Linux）
python3 -m pip install --user pipx && pipx ensurepath
pipx install black → black --version
“やってはいけない”チェックリスト
sudo pip install ...（システム汚染）
仮想環境の外で pip install
pip freeze をそのまま配布用 requirements.txt に採用（不要依存混入）
conda の base で pip 多用（環境が崩れやすい）
すぐ使える雛形（コピペOK）
macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Windows（PowerShell）
py -3 -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
よくあるつまずき（FAQスタイル）
「pip: command not found」
PATH未設定 or Python未導入。
対処：python -m pip --version で確認。必要なら Python 再インストール時に「PATHに追加」を有効化。
「どの Python に入っているかわからない」
対処：python -c "import sys;print(sys.executable)" と python -m pip --version で経路確認。
原則：python -m pip を徹底。
「ライブラリを入れたのに import できない」
別の仮想環境/別のPythonに入っている可能性。
対処：仮想環境を有効化してから python -m pip install。which python / Get-Command python で実行器確認。
「依存が壊れた/動かない」
対処：requirements.txt を固定し、疑わしいものだけ -U。最悪は新しい環境を作り直すのが早い。
まとめ（運用の型）
実行は python -m pip。
作業は 仮想環境の中。プロジェクト単位で作る。
依存は requirements.txt と constraints.txt で固定。
開発者ツールは pipx で隔離。
壊れたら新しい環境を作り直すのが最短。
