pip install が「error: externally-managed-environment」で失敗する（PEP 668）

システムの Python に pip install すると externally-managed-environment で弾かれるのは PEP 668 の保護。
OS のパッケージ管理と衝突させないための仕組みで、仮想環境か pipx を使うのが正攻法。

#pip #pep-668 #venv #break-system-packages #install #python

公開: 2026-06-30更新: 2026-09-10

実行例あり（2026-08-02 に実環境で検証）

要約

error: externally-managed-environment は、その Python が「OS など外部のパッケージ管理に任されている」とマークされているのに、pip で直接パッケージを入れようとしたときに出る。
Python 3.11・pip 23.0 以降が PEP 668（新しいタブで開く）のマーカー（EXTERNALLY-MANAGED ファイル）を見て、仮想環境の外での書き換えを止めている。
OS のパッケージと pip が同じ場所を取り合って壊れるのを防ぐためで、回避ではなく仮想環境 (venv) か pipx へ寄せるのが正攻法。

実行例

実際に上記の手順を 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.
$ echo $?
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
$ echo $?
0

— 2026-08-02 時点の出力

検証環境

検証日: 2026-08-02
実行環境: python:3.12

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

システム Python に直接 install: Debian/Ubuntu や Homebrew が入れた Python に、venv の外から pip install している。
マーカーの存在: ディストリ側が標準ライブラリのフォルダに EXTERNALLY-MANAGED を置いており、pip がそれを検知している。
sudo での全体導入: sudo pip install でシステム全体を書き換えようとしている。
venv 有効化忘れ: 仮想環境を作ったのに有効化しておらず、システム側へ入りかけている。
コンテナ / CI: Dockerfile で root のシステム Python にそのまま入れている。

解決策

1. 仮想環境を使う（推奨）

プロジェクト直下に venv を作り、有効化してから入れる。

python -m venv .venv
source .venv/bin/activate      # Windows は .venv\Scripts\activate
pip install requests

有効化中はマーカーの対象外なので、この警告は出ない。venv 公式ドキュメント（新しいタブで開く）のとおりプロジェクト単位で環境を切るのが基本で、which pip が .venv 内を指していれば PEP 668 のガードには当たらない。

2. CLI ツールは pipx

コマンドとして使うツール（black, httpie 等）は pipx で隔離する。

pipx install black

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

3. どうしてもシステムに入れるとき

壊れても自分で直せる前提で、明示的に許可フラグを付ける。

pip install --break-system-packages SomePackage

OS が用意するパッケージがあるなら apt install python3-requests のように OS 側で入れるほうが安全。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 の常用も避けられる。

要約

実行例