pip install が Permission denied で失敗する

要約

pip install が Permission denied または error: externally-managed-environment で失敗するのは、システム Python の site-packages に書こうとしているから。
仮想環境 (venv) を作って activate してから install するのが正攻法。sudo pip は OS の Python を壊すリスクがあるため使わない。

よくある原因

1. システム Python に書き込もうとする: /usr/lib/python3.x/site-packages などは root 所有で一般ユーザに書き込み権が無い
2. venv を作らず開発: プロジェクトごとに環境を切らず、global を直接汚そうとしている
3. activate 忘れ: .venv は作ってあるが、シェルを開き直して activate していない
4. PEP 668 のガード: Python 3.11 以降の Debian / Ubuntu 等では、システム環境への install は明示的に拒否される

解決策

1. venv を使う（推奨）

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

pip 公式ユーザガイド でも、プロジェクト単位の venv が推奨。which pip で venv 内の pip を指しているか確認する。

2. CLI ツールには pipx

python3 -m pip install --user pipx
pipx install black
pipx install poetry

pipx は各ツールごとに独立 venv を作って公開コマンドだけシンボリックリンクする。
グローバル環境を汚さず、pipx upgrade で個別更新できる。

3. --user オプション

pip install --user requests

~/.local/lib/python3.x/site-packages に入る。
venv が使えない CI や、システム全体ではなく自分だけ使いたい場合に有効。
ただし複数プロジェクトの依存衝突は防げないので、開発用途には venv の方が無難。

4. sudo pip install は使わない

# NG: OS パッケージマネージャと喧嘩する
sudo pip install requests

PEP 668 で標準化された通り、ディストリ提供の Python は OS 側で管理されている。
ここに pip で上書きすると、apt で入れた他パッケージが壊れる。