「error: externally-managed-environment」の正体：PEP 668とpip/apt競合、venv隔離が推奨される理由

はじめに

比較的新しいバージョンのDebian/Ubuntuなどでpip installを実行すると、次のようなエラーに遭遇することがあります。

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

以前は問題なく通っていたはずのpip installが、突然拒否されるようになった――という状況に驚いた方も多いはずです。本記事では、このエラーの背景にあるPEP 668という仕様と、推奨される対処法を整理します。

なぜこのエラーが生まれたのか

OS(Debian/Ubuntuなど)は、Pythonのシステム全体用ディレクトリ(サイトパッケージ)に、aptなどのパッケージ管理ツールを通じて多数のPythonパッケージをインストールしています。OS自身のツール(例えば一部のシステムユーティリティ)がPython製で、特定バージョンのライブラリに依存していることも珍しくありません。

ここにpip installでシステム全体向けにパッケージをインストール・アップグレードしてしまうと、OSが管理しているファイルを意図せず上書きしてしまい、aptをはじめとするシステムツールが壊れる事故が起こり得ます。この事故を防ぐために生まれたのがPEP 668(「PythonのベースとなるOS環境を、外部管理下にあるものとしてマークする」仕様)です。

PEP 668の仕組み

PEP 668に対応したディストリビューションは、Pythonの標準ライブラリディレクトリにEXTERNALLY-MANAGEDという名前のマーカーファイルを配置します(例: /usr/lib/python3.12/EXTERNALLY-MANAGED)。このファイルには、ディストリビューション側が用意した独自のエラーメッセージも含まれています。

pipはこのマーカーファイルの存在を検知すると、システム全体へのパッケージのインストール・アンインストール・アップグレードを拒否するようになります。これは2022年に採択された仕様で、主要なLinuxディストリビューションや、macOS向けのHomebrewでも順次採用が進んでいます。

対処法

推奨: 仮想環境(venv)を使う

最も推奨される対処法は、システム全体のPython環境を触らず、プロジェクトごとに独立した仮想環境(venv)を作成し、その中でpip installを行うことです。

python3 -m venv myenv
myenv/bin/pip install some-package

仮想環境内へのインストールはOS管理下のディレクトリに影響しないため、externally-managed-environmentエラーは発生しません。

代替策1: aptでインストールする

そのパッケージがDebian/Ubuntuのリポジトリにpython3-xyzのような形で用意されている場合、apt install python3-xyzのようにOS標準のパッケージ管理経由でインストールする方法もあります。ただし、PyPI(Python Package Index)にある最新版と、ディストリビューションのリポジトリにあるバージョンにはズレがあることが多く、常に最新版を使いたい場合には向きません。

代替策2: --break-system-packagesフラグ(非推奨・注意が必要)

pip install --break-system-packages some-package

このフラグを付けると、PEP 668の保護を無視して強制的にシステム全体へインストールできます。文字通り「システムパッケージを壊す可能性がある」ことを承知の上で使うオプションであり、本番サーバー(特にOSの中核機能に関わるツールが動いている環境)では特に注意が必要です。筆者も実際に、この方式を試した際にOS標準パッケージとの依存関係の競合(アンインストール時の記録ファイル不整合エラー)に遭遇し、システムのPython環境を壊しかけた経験があります。以降は迷わずvenvに隔離する方針に切り替えました。

まとめ

参考

• PEP 668 – Marking Python base environments as "externally managed" | peps.python.org
• "Externally managed environments": when PEP 668 breaks pip