pip install で「externally-managed-environment」エラーが解決できない

要約

error: externally-managed-environment は、PEP 668 に従う OS の Python（Debian 12 / Ubuntu 23.04 以降、Homebrew Python など）が、システム環境への直接 pip install を拒否しているために出る。
OS パッケージマネージャと pip が同じ場所を奪い合うのを防ぐガード。仮想環境 (venv) を作ってその中に入れる のが正攻法。

よくある原因

1. システム Python へ直接 install: pip install requests をディストリ提供の Python に対して実行している
2. venv 未使用: プロジェクトごとに環境を切らず global を汚そうとしている
3. PEP 668 マーカー: 配布 Python に EXTERNALLY-MANAGED ファイルが置かれ、pip がそれを尊重している
4. コンテナ / CI: Dockerfile で root のシステム Python にそのまま入れている

解決策

1. venv を作る（推奨）

python3 -m venv .venv
source .venv/bin/activate      # Windows は .venv\Scripts\activate
pip install -r requirements.txt

venv 公式ドキュメント のとおり、プロジェクト単位の仮想環境が基本。which pip が .venv 内を指していれば PEP 668 のガードに当たらない。

2. CLI ツールは pipx

sudo apt install pipx          # もしくは python3 -m pip install --user pipx
pipx install black
pipx install poetry

pipx はツールごとに独立 venv を作り、コマンドだけを公開する。
グローバル環境を汚さずに済む。

3. 一時的にガードを外す（非推奨）

pip install --break-system-packages <pkg>

PEP 668 で定義された保護を意図的に無効化するフラグ。apt 管理のパッケージと競合し得るため、検証用の使い捨て環境などに限定する。
常用しない。

4. Docker / CI でも venv を切る

RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install -r requirements.txt

コンテナでも仮想環境を 1 つ作って PATH を通せば、システム Python を触らずに済み、--break-system-packages の常用も避けられる。