externally-managed-environment

定義

externally-managed-environment は、OS 側のパッケージマネージャが所有している Python 環境に対して pip install を実行したとき、pip がインストールを拒否して出すエラーである。
PEP 668 で標準化された仕組みで、その環境の標準ライブラリのディレクトリに EXTERNALLY-MANAGED という名前のマーカーファイルが置かれていると発動する。

詳細

このマーカーは Debian 12 以降・Ubuntu 23.04 以降・Fedora・Homebrew の Python に同梱されている。
システムの Python は OS 自身の管理ツールが依存しているため、pip がその配下のパッケージを上書きしたり削除したりすると、パッケージ管理コマンド自体が動かなくなる。
PEP 668 は、壊れてから気づく事態を避けるために配布元がマーカーを置き、pip がそれを尊重して最初に止める、という取り決めである。

正しい回避は環境を分けることで、python3 -m venv .venv を作ってその中の pip を使えばマーカーの外に出る。
コマンドラインツールを入れたいだけなら pipx を使う手もある。

よくある誤解

• --break-system-packages を付ければ解決する: 拒否を黙らせるだけで、システムの Python を壊す危険は残ったままである。
  恒久策は pip install が「externally-managed-environment」で失敗する の通り仮想環境に寄せることである。
• pip の不具合である: pip 側のバグではない。
  ディストリビューションが意図して置いたマーカーに pip が従っているだけである。

関連

環境を分ける仕組みそのものは venv、パッケージの取得元は PyPI が担う。
CI のようにコンテナ全体が使い捨ての環境では、マーカーを外す運用が選ばれることもある。