pip install で「externally-managed-environment」エラーが解決できない
PEP 668 に従う Debian 12 / Ubuntu 23.04 以降や Homebrew Python は、システム環境への直接 pip install を禁止する。
venv を作ってその中で入れるのが正攻法で、CLI ツールは pipx を使う。
公開: 更新:
要約
error: externally-managed-environment は、PEP 668 に従う OS の Python（Debian 12 / Ubuntu 23.04 以降、Homebrew Python など）が、システム環境への直接 pip install を拒否しているために出る。
OS パッケージマネージャと pip が同じ場所を奪い合うのを防ぐガード。仮想環境 (venv) を作ってその中に入れる のが正攻法。
よくある原因
- システム Python へ直接 install:
pip install requestsをディストリ提供の Python に対して実行している - venv 未使用: プロジェクトごとに環境を切らず global を汚そうとしている
- PEP 668 マーカー: 配布 Python に
EXTERNALLY-MANAGEDファイルが置かれ、pip がそれを尊重している - コンテナ / CI: Dockerfile で root のシステム Python にそのまま入れている
解決策
1. venv を作る（推奨）
python3 -m venv .venv
source .venv/bin/activate # Windows は .venv\Scripts\activate
pip install -r requirements.txtvenv 公式ドキュメント（新しいタブで開く） のとおり、プロジェクト単位の仮想環境が基本。which pip が .venv 内を指していれば PEP 668 のガードに当たらない。
2. CLI ツールは pipx
sudo apt install pipx # もしくは python3 -m pip install --user pipx
pipx install black
pipx install poetrypipx はツールごとに独立 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 の常用も避けられる。
実行例
実際に上記の手順を python:3.12（Debian GNU/Linux 13 / trixie）環境で動かすと、EXTERNALLY-MANAGED マーカーを設置したシステム Python への直接インストールでは終了コード 1 の error: externally-managed-environment が再現し、venv 経由では終了コード 0 で six 1.17.0 のインストールが成功することを確認できる。
$ pip install --quiet requests
error: externally-managed-environment
× This environment is externally managed
╰─> Debian/Ubuntu のような配布 Python を模した検証用マーカー。
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
pip の終了コード: 1$ python -m venv .venv$ . .venv/bin/activate$ python -c "import sys; print('venv prefix:', sys.prefix)"
venv prefix: /tmp/tmp.2aSTLjtzMO/.venv$ pip install --quiet six
[notice] A new release of pip is available: 25.0.1 -> 26.2
[notice] To update, run: pip install --upgrade pip$ python -c "import six; print('installed in venv, six:', six.__version__)"
installed in venv, six: 1.17.0
終了コード: 0（0 なら解消）— 2026-08-02 時点の出力