pipでPythonパッケージをインストールする際の「error: externally-managed-environment」を修正する

エラーの内容

シンプルな pip install コマンドを実行すると、以下のエラーが表示されます：

$ pip install requests
error: externally-managed-environment

× This environment is managed by an external package manager.
╰─> To install Python packages system-wide, use 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. Make
    sure you have the python3-full apt package installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have the pipx package
    installed.

    If you are using a Python Virtual Environment (like .venv), make
    sure it is active before running pip install. Consult the
    python3 venv documentation for instructions.

    For more information, visit https://packaging.python.org/en/latest/specifications/externally-managed-environments/

根本原因

Python 3.11 と PEP 668 以降、Ubuntu 23.04+、Debian 12 (Bookworm)、Fedora 38+ などのディストリビューションは、システム Python を「外部管理」としてマークするようになりました。apt や dnf などのディストリビューションのパッケージマネージャーがその Python インストールを管理しており、pip はそこに手を加えることができません。

この変更以前は、pip install がシステム Python の site-packages にパッケージを黙って追加していました。これが深刻な問題を引き起こしていました。pip でインストールしたパッケージがディストリビューション提供のパッケージと衝突し、特定バージョンに依存するシステムツールが壊れることがありました。たとえば、パッケージマネージャーが python3-requests を 2.28 から 2.31 に更新すると、古い API にピン留めされた pip インストール済みパッケージが静かに壊れることがありました。

このブロックは単一のマーカーファイルによって強制されています：

/usr/lib/python3.x/EXTERNALLY-MANAGED

pip はそのファイルを検出すると処理を拒否します。それだけのことです。

解決策：仮想環境を使う（正しい方法）

ほとんどの場合、これが最善策です。仮想環境を使えば、プロジェクト専用の隔離された Python とパッケージディレクトリが確保され、システム Python とは完全に分離されます。

ステップ 1：仮想環境を作成する

# プロジェクトディレクトリ内で
python3 -m venv .venv

ステップ 2：仮想環境を有効化する

# Linux/macOS の場合
source .venv/bin/activate

# Windows の場合（WSL でない環境）
.venv\Scripts\activate

ステップ 3：通常通りパッケージをインストールする

pip install requests

動作確認

# pip の解決先を確認する
which pip
# 表示例: /your/project/.venv/bin/pip

# パッケージがインストールされたか確認する
pip show requests

作業が終わったら、以下のコマンドで無効化します：

deactivate

解決策：CLI ツールには pipx を使う

スタンドアロンのコマンドラインツールをインストールする場合は、プロジェクトの venv を使わないでください。pipx はまさにこのような用途のために作られています。ツールごとに隔離された環境を作成し、バイナリを PATH に自動的に追加してくれます。後は何も気にする必要がありません。

# pipx をインストール
sudo apt install pipx
pipx ensurepath

# CLI ツールをインストール
pipx install black
pipx install httpie

これで black や http はどこからでも使えます。venv を有効化する必要も、環境を管理する手間もありません。

解決策：ブロックを強制的に回避する（手軽だがリスクあり）

--break-system-packages フラグを使ってブロックを強制的に突破することができます：

pip install requests --break-system-packages

このフラグ名は意図的に怖く命名されています。何か問題が起きても自己責任だということです。

正当な使用例もあります。たとえば Docker コンテナの中であれば、システムはすでに隔離されており、パッケージの競合を気にする必要がありません。しかし実際の開発マシンで使うのはやめましょう。システムパッケージと衝突した pip インストール済みパッケージが、apt、ネットワークマネージャー、あるいはシステム Python に依存するあらゆるものを壊してしまう可能性があります。

解決策：マーカーファイルを削除する（非推奨）

エラーを引き起こすファイルを削除するよう勧めているガイドもあります：

# ファイルの場所を確認する
python3 -c "import sys; print(sys.prefix)"

# Ubuntu 23.10 の場合のパス例
sudo rm /usr/lib/python3.11/EXTERNALLY-MANAGED

確かに動きます。しかしこれは、火災報知器のバッテリーを抜くのと同じようなものです。保護機能が永久に失われ、以後の pip インストールがシステムパッケージを静かに上書きするようになります。venv を作るのに 10 秒もかかりません。素直にそちらを使いましょう。

解決策：システム全体で必要なパッケージは apt でインストールする

パッケージによっては、特定のプロジェクトだけでなくシステム全体で利用可能にする必要がある場合もあります。ディストリビューションが既に提供していないか確認してみましょう：

# 利用可能なパッケージを検索する
apt search python3-requests

# apt でインストールする
sudo apt install python3-requests

apt でインストールしたパッケージはシステムにきれいに組み込まれ、このエラーが発生することもありません。欠点は、ディストリビューションのパッケージが PyPI より数ヶ月遅れる場合があることです。

よくあるシナリオ：新しいプロジェクトをゼロから始める

最初から最後までの完全なワークフローです：

# 1. python3-venv がインストールされているか確認する（Ubuntu）
sudo apt install python3-venv python3-full

# 2. プロジェクトを作成する
mkdir myproject && cd myproject

# 3. 仮想環境を作成する
python3 -m venv .venv

# 4. 有効化する
source .venv/bin/activate

# 5. 自由にパッケージをインストールする
pip install flask sqlalchemy gunicorn

# 6. 依存関係を保存する
pip freeze > requirements.txt

よくあるシナリオ：Docker コンテナ

Debian や Ubuntu のベースイメージでも Dockerfile でこのエラーが発生します。コンテナはすでに隔離されているため、ここでは --break-system-packages を使うのが現実的な選択です：

FROM python:3.12-slim

COPY requirements.txt .
RUN pip install --break-system-packages -r requirements.txt

他の選択肢としては、公式の python:3.12 イメージ（制限なし）に切り替えるか、より厳密な隔離が必要であればコンテナ内に proper な venv を作成する方法もあります。

予防策

すべての Python プロジェクトの開始時に .venv を作成しましょう。問題が起きてから対処するのではなく、リポジトリを作成するのと同じように習慣化してください。
すぐに .venv/ を .gitignore に追加しましょう。
ライブラリではなく CLI ツールをインストールするときは pipx を使いましょう。
チームで作業している場合は、venv のセットアップ手順を README に記載しましょう。後から参加するメンバーが助かります。
uv も検討してみてください。pip と venv を置き換える Rust 製ツールで、10〜100 倍高速で環境の作成も自動化できます：uv venv && uv pip install requests。