pip installで「error: externally-managed-environment」が出る原因と解決策

Ubuntu/DebianやMac（Homebrew）のPython環境でpip installを実行すると、次のようなエラーが出てインストールに失敗することがあります。

$ pip install requests
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.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip.

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やPythonの不具合ではなく、PEP 668という仕様に基づく「意図された保護機能」です。この記事では、なぜこのエラーが出るのかという仕組みと、状況別の正しい解決策（venv・pipx・OSパッケージ・--break-system-packages）を解説します。

「externally-managed-environment」エラーが発生する環境

このエラーは、OSやパッケージマネージャが管理しているPython（システムPython）に対して直接pip installしたときに発生します。主な発生環境は以下の通りです。

Debian 12（bookworm）以降
Ubuntu 23.04以降
Raspberry Pi OS（bookworm）以降
macOSのHomebrewでインストールしたPython
その他、PEP 668を採用したLinuxディストリビューション

エラーメッセージの文面は環境によって少し異なり、Debian/Ubuntuではapt install python3-xyz、Homebrewではbrew install xyzを使うよう案内されます。

原因：PEP 668によるシステムPythonの保護

従来、OSに最初から入っているPythonに対してsudo pip installなどで直接パッケージを入れると、aptやbrewが管理しているファイルとpipが入れたファイルが食い違い、最悪の場合OS付属のツールが動かなくなる問題がありました。

そこでPEP 668では、ディストリビューション側が「このPython環境は外部のパッケージマネージャ（aptやbrew）が管理している」と宣言できる仕組みが導入されました。具体的には、Python標準ライブラリのディレクトリにEXTERNALLY-MANAGEDという名前のファイルが置かれている環境では、pip（バージョン23.0以降）がシステム環境への直接インストールを拒否します。

# 標準ライブラリのディレクトリを確認
python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))"

# そのディレクトリにEXTERNALLY-MANAGEDファイルがあればこのエラーが出る
ls /usr/lib/python3.12/EXTERNALLY-MANAGED

ポイントは、pip install --userによるユーザー単位のインストールも同様にブロックされることです。エラーを回避するには、次に紹介するいずれかの方法を使います。

解決策1：仮想環境（venv）を作ってインストールする（推奨）

ライブラリを自分のプロジェクトのコードから使いたい場合は、仮想環境（venv）を作ってその中にインストールするのが基本です。仮想環境の中はシステムPythonから切り離されているため、このエラーは発生しません。

# プロジェクトのディレクトリで仮想環境を作成
python3 -m venv .venv

# 仮想環境を有効化
source .venv/bin/activate

# 仮想環境の中では今まで通りpip installできる
pip install requests

作業を終えるときはdeactivateコマンドで仮想環境から抜けられます。

Debian/Ubuntuでpython3 -m venv自体が失敗する場合は、venvモジュールが別パッケージに分離されているので、先にインストールしてください。

sudo apt install python3-venv

なお、仮想環境の有効化を忘れた状態でスクリプトを実行すると、今度はインストールしたはずのモジュールが見つからずModuleNotFoundErrorになります。この症状については「Pythonのvenvで「No module named」が発生する原因と解決法」で詳しく解説しています。

解決策2：コマンドとして使うツールならpipxでインストールする

yt-dlpやansible、blackのように、ライブラリとしてimportするのではなくコマンドとして使うツールをインストールしたい場合は、pipxが最適です。pipxはツールごとに独立した仮想環境を自動で作り、コマンドだけをPATHに通してくれます。

# pipx自体のインストール
sudo apt install pipx    # Debian/Ubuntuの場合
brew install pipx        # macOS（Homebrew）の場合

# PATHの設定（初回のみ。設定後はターミナルを開き直す）
pipx ensurepath

# ツールのインストール
pipx install yt-dlp

解決策3：OSのパッケージマネージャでインストールする

システム全体で使いたいライブラリがディストリビューションのパッケージとして提供されている場合は、pipではなくOSのパッケージマネージャでインストールするのが最も安全です。エラーメッセージが案内しているのもこの方法です。

# Debian/Ubuntuではパッケージ名は「python3-ライブラリ名」の形式が多い
sudo apt install python3-requests

# パッケージ名が分からない場合は検索できる
apt search python3-requests

ただしOSパッケージのライブラリはバージョンが古いことが多いため、最新版が必要な開発用途では解決策1のvenvを使ってください。

非推奨：--break-system-packagesで強制インストールする

エラーメッセージ末尾に書かれている通り、--break-system-packagesフラグを付ければ保護を無視して強制的にインストールできます。

pip install requests --break-system-packages

ただし、フラグ名の通り「システムのパッケージを壊す可能性がある」ことを了承した上での操作です。aptやbrewが管理するファイルとの整合性が崩れ、OSのアップグレードやbrew upgradeの際に問題が起きることがあります。使うのは、壊れても作り直せるDockerコンテナやCI環境などに限定するのが無難です。

コンテナ環境では、環境変数で同じ指定をしておく方法もあります。

# Dockerfileで指定する場合
ENV PIP_BREAK_SYSTEM_PACKAGES=1

また、EXTERNALLY-MANAGEDファイルを削除するという回避策を紹介している記事もありますが、Python側のパッケージ更新でファイルが復活することがある上、保護を失ったままシステムPythonを汚すことになるため、おすすめしません。

まとめ

error: externally-managed-environmentは、pipの不具合ではなくPEP 668によるシステムPythonの保護機能
ライブラリをプロジェクトで使いたい場合は、venvを作ってその中でpip installする（基本はこれ）
コマンドとして使うツールはpipx installでインストールする
ディストリビューションのパッケージがあるならapt install python3-xxxも選択肢
--break-system-packagesは使い捨て環境限定の最終手段。EXTERNALLY-MANAGEDファイルの削除は非推奨

pip関連では「Could not find a version that satisfies the requirementエラーの解決方法」もあわせて参考にしてください。