できない.dev

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

error: externally-managed-environment は、OS 管理の Python に直接 pip install すると出る。
venv を作って有効化するか、CLI ツールは pipx で入れれば直る。

公開: 更新:

症状できない · exit 1
pip install --quiet requests
…
error: externally-managed-environment
× This environment is externally managed
╰─> Debian/Ubuntu のような配布 Python を模した検証用マーカー。
解決後できた · exit 0
python -c "import six; print('installed in venv, six:', six.__version__)"
installed in venv, six: 1.17.0

2026-08-02 に python:3.12 で実際に打って取った出力。検証環境の詳細

要約

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

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

解決策

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 の常用も避けられる。

よくある原因

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