externally-managed-environmentの直し方｜pip

RJC Techチーム

error: externally-managed-environment は、OS（apt など）が管理している Python に、pip で直接パッケージを入れようとしたときに、pip が止めるエラーです。 Ubuntu 24.04 や Debian 12 など、新しい版の OS の Python で出ます。pip と apt が同じ場所に別々にパッケージを入れると、OS のツールが壊れることがあるためです。

直し方は「OS の Python に直接入れない」ことです。目的ごとに入れ方を選びます。

やりたいこと	入れ方	コマンドの例
プロジェクトでライブラリを使う	venv（仮想環境）	`python3 -m venv .venv` → `.venv/bin/pip install requests`
コマンドとして使うツールを入れる	pipx	`pipx install black`
OS 全体で使う（apt にあるもの）	apt	`sudo apt install python3-requests`
速く・まとめて管理したい	uv	`uv venv` → `uv pip install requests`

確認環境：Ubuntu 24.04.4、Python 3.12.3（apt）、pip 24.0、pipx 1.4.3（確認日 2026年10月11日）。一般ユーザーと root の両方で再現しました。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

（記載例）出典：株式会社RJC「externally-managed-environmentの直し方｜pip」

再現：pip install で止まる

$ python3 -m pip install six
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. Make
    sure you have python3-full 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 pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

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.

試したこと	結果
`python3 -m pip install six`（一般ユーザー）	エラー
`python3 -m pip install --user six`（自分のホームに入れる）	エラー（`--user` でも止まる）
`sudo python3 -m pip install`（root）	エラー
venv の中の pip	入る

エラー文の中に、直し方（apt・venv・pipx）がそのまま書かれています。 以下は、その3つと uv を、実際に動かした結果です。

なぜ出るのか：EXTERNALLY-MANAGED という目印のファイル

Python の標準ライブラリのフォルダーに EXTERNALLY-MANAGED というファイルがあると、pip は仮想環境の外へのインストールを止めます（PEP 668 として定められた仕組み）。

$ cat /usr/lib/python3.12/EXTERNALLY-MANAGED
[externally-managed]
Error=To install Python packages system-wide, try apt install
 python3-xyz, where xyz is the package you are trying to
 install.
 ...

Python の種類	このエラー
Ubuntu・Debian の apt で入れた Python（`/usr/bin/python3`）	出る
venv・uv で作った仮想環境の中	出ない
ソースからビルドした Python（pyenv など）	仕様では、目印のファイルが無いため出ない

Python のパッケージング仕様では、このチェックは仮想環境の外でだけ行われます。仮想環境に入れる限り、このエラーは起きません。

直し方1：venv（プロジェクトのライブラリ）

cd myproject
python3 -m venv .venv               # 仮想環境を作る（最初の1回）
. .venv/bin/activate                # 有効にする（Windows は .venv\Scripts\activate）
pip install six                     # 仮想環境の中に入る

$ which python pip
/tmp/v12/bin/python
/tmp/v12/bin/pip                    ← 仮想環境の pip を使っている
$ pip install six
Successfully installed six-1.17.0

activate を使わずに、.venv/bin/python や .venv/bin/pip をフルパスで実行しても同じです。cron やスクリプトでは、こちらのほうが確実です。

venv の部品が入っていないと、python3 -m venv が次のエラーになりました。案内どおり sudo apt install python3.12-venv（版に合わせる）で入れてから、作り直します。

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.12-venv

直し方2：pipx（コマンドとして使うツール）

black・ruff・httpie などのコマンドとして使うツールは、pipx で入れます。pipx はツールごとに専用の仮想環境を作り、コマンドだけを ~/.local/bin に置きます。

sudo apt install pipx
pipx ensurepath                     # ~/.local/bin を PATH に追加（最初の1回）
pipx install pycowsay

$ pycowsay hi
  --
< hi >
$ pipx list --short
pycowsay 0.0.0.2

直し方3：apt（OS の Python で使う）

OS の Python から使いたいライブラリが apt にあるなら、apt で入れます。名前は python3-パッケージ名 です。

$ apt-cache policy python3-requests
python3-requests:
  Installed: (none)
  Candidate: 2.31.0+dfsg-1ubuntu1.2

apt の版は、PyPI の最新版より前の版のことがあります。最新版が必要なら venv を使います。

直し方4：uv

uv を使っている場合は、uv が仮想環境を作るので、このエラーは出ません。

uv venv                       # .venv を作る
uv pip install six            # .venv に入る

確認環境でも、Ubuntu の Python 3.12 を元に uv venv で作った環境に、問題なく入りました。

--break-system-packages を使わないほうがよい理由

エラー文にある --break-system-packages を付けると、チェックを飛ばしてインストールできます。

$ python3 -m pip install --user --break-system-packages pycowsay
Successfully installed pycowsay-0.0.0.2
Location: /home/dev/.local/lib/python3.12/site-packages

起きうること	内容
OS のツールが動かなくなる	apt が入れたライブラリと違う版が先に読み込まれ、OS の Python 製のツールが想定外の版で動く
apt で更新・削除したときにぶつかる	pip と apt が、同じライブラリを別々に管理する状態になる
何を入れたか分からなくなる	プロジェクトごとの依存が OS 全体に混ざる

名前のとおり「システムを壊しうる」オプションです。仕様でも、既定では無効で、危険であることが分かる名前にするよう定められています。使うのは、壊れてもすぐ作り直せる使い捨ての環境に限ります。

Docker・CI での書き方

状況	おすすめ
Debian・Ubuntu のイメージに apt で Python を入れている	Dockerfile の中で venv を作り、PATH を通す
GitHub Actions の `actions/setup-python` を使う	setup-python で入れた Python に pip を使う
Ubuntu のランナーの OS の Python を使う	venv を作ってから pip

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3 python3-venv
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"          # 以降の python・pip は venv のもの
COPY requirements.txt .
RUN pip install -r requirements.txt

ENV PATH で venv の bin を先頭に置くと、以降の python・pip は venv のものになり、activate は要りません。確認環境でも、venv の bin を PATH の先頭に置くと、which pip が venv の pip を指し、そのまま pip install できました。

確認の手順（チェックリスト）

順番	確認すること	方法
1	どの Python の pip か	`python3 -m pip --version`（`/usr/lib/python3/...` なら OS の Python）
2	仮想環境の中か	`which python`（`.venv/bin/python` ならOK）
3	入れたいのはライブラリかツールか	ライブラリは venv、ツールは pipx
4	venv が作れない	`python3-venv` を apt で入れる
5	Docker・CI	venv を作って PATH を通す