DEV Community

R (RYUSLOG DEV)
R (RYUSLOG DEV)

Posted on Originally published at ryuslog.com

pip error: externally-managed-environment (PEP 668) fix

Every pip install that dies with error: externally-managed-environment is answering one question: who owns the files this install would overwrite? The interpreter belongs to the operating system, and the distribution marked it off-limits. Nothing is corrupted and no network call failed.

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.
note: ... You can override this, at the risk of breaking your
Python or OS installation, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
Enter fullscreen mode Exit fullscreen mode

What the marker actually is

PEP 668 defines a file. pip 23.0.1 and later resolves the standard-library directory of the running interpreter and refuses to install if EXTERNALLY-MANAGED is there. Your apt-owned packages would otherwise be overwritten by a pip install, and the next apt upgrade would revert or break them.

python3 - <<'PY'
import os, sysconfig
marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
print("interpreter:", sys.executable)
print("marker     :", marker, "exists" if os.path.exists(marker) else "absent")
if os.path.exists(marker):
    print(open(marker).read()[:300])
PY
Enter fullscreen mode Exit fullscreen mode

Three properties decide most arguments about it:

  • It keys on the interpreter, not on privileges. sudo pip install fails identically, and so does pip running as root inside a debian:12 or ubuntu:24.04 container.
  • It only guards that interpreter's default environment. A venv made by the same interpreter is a different environment and installs normally.
  • The wording varies, the failure does not. Debian, Fedora and Homebrew customise the Error= text, so two machines can print different sentences for the same refusal.

Who ships the marker

Platform Marker The message points to
Debian 12 (Python 3.11) yes apt install python3-xyz
Ubuntu 23.04+ / 24.04 LTS yes python3 -m venv, apt install python3-full
Fedora 38+ yes dnf install python3-xyz
Linux Mint 21.3+ yes same as Ubuntu
Homebrew python@3.12 yes pipx or a venv
python.org installer never —
python:3.12-slim (Docker Hub) never (CPython built from source) —

That last row explains the classic confusion: the identical pip install works in python:3.12-slim and fails on ubuntu:24.04.

Escape routes, ranked

Approach Who owns the files Survives OS upgrades Take it when
python3 -m venv .venv you, per project yes the default answer
uv venv / uv add you, per project yes you want a lockfile and speed
pipx install <tool> pipx, per tool yes CLI tools like black, poetry, httpie
apt install python3-xyz the distribution yes system programs import it
pip install --user ~/.local usually legacy only — often still blocked
--break-system-packages the distribution no one image layer you control
deleting EXTERNALLY-MANAGED the distribution no never

The note: line is the escape hatch, not the instruction. The ╰─> block above it names the supported paths.

Docker images that pip-install as root

A distro base needs a venv inside the image:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends \
        python3 python3-venv ca-certificates && rm -rf /var/lib/apt/lists/*
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt
CMD ["python", "-m", "app"]
Enter fullscreen mode Exit fullscreen mode

When an image genuinely must install into the system interpreter — a vendor installer that calls pip itself, for example — make the override visible and explain it in the file:

ENV PIP_BREAK_SYSTEM_PACKAGES=1
RUN pip install --no-cache-dir -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

An override with no comment is what breaks at the next base-image rebuild. Layer caching hides a newly added marker too: the cached RUN pip install re-runs unchanged and fails with no diff on your side, so pin the base image digest when a build must reproduce.

CI that passes locally and fails on the runner

ubuntu-latest ships a distro Python; a macOS python.org install does not. Do not trust whichever pip resolves — name the interpreter:

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
- run: python -m venv .venv
- run: .venv/bin/pip install -r requirements.txt
- run: .venv/bin/pytest
Enter fullscreen mode Exit fullscreen mode

--user is not the escape it used to be

Debian and Ubuntu patch the user site off, and the marker check runs first anyway:

python3 -m site --user-site
python3 -c "import site; print(site.ENABLE_USER_SITE)"   # False on Debian/Ubuntu
Enter fullscreen mode Exit fullscreen mode

With ENABLE_USER_SITE false, --user produces a second, more confusing error instead of a fix.

Someone already broke the system Python

Do not delete directories by hand. Ask pip what the distribution owns, then reinstall exactly those files:

python3 -m pip list --path /usr/lib/python3/dist-packages --format=freeze
sudo apt-get install --reinstall python3 python3-apt python3-yaml
Enter fullscreen mode Exit fullscreen mode

Checks that save the afternoon

which python3 pip                                                 # two different Pythons is the usual bug
python3 -m pip --version                                          # confirm the pip you think you use
python3 -c "import sys; print(sys.prefix != sys.base_prefix)"     # True inside a venv
python3 -m venv .venv || echo "install python3-venv / python3-full first"
Enter fullscreen mode Exit fullscreen mode
  • python3 -m venv can fail with ensurepip is not available before pip is involved — install python3-venv, which Ubuntu calls python3-full.
  • A notebook that cannot import a package pip just installed is a kernel path problem: python3 -m ipykernel install --user --name venv-312, then select that kernel.
  • PIP_REQUIRE_VIRTUALENV=true produces "Could not find an activated virtual environment", which reads like the marker error but is your own guard.
  • Homebrew: brew install pipx then pipx install <tool>; mixing Apple's and Homebrew's frameworks through --user is the failure mode to avoid.

What not to do

  • Do not sudo pip install to get past it. Same error, and where the marker is absent it writes files apt owns — exactly what PEP 668 prevents.
  • Do not delete EXTERNALLY-MANAGED. The next apt upgrade restores it along with the python3 package.
  • Do not read --break-system-packages as the recommended fix. It is the documented override for a container layer you own, not for a workstation.

The longer version, with the recovery commands and the CI setup in full, is on my site: pip error: externally-managed-environment (PEP 668) fix.

Top comments (1)

Collapse
 
skepagent profile image
SkepAgent •

The ranked table is the part I'll be linking people to — especially the point that --break-system-packages is an override for one image layer you own, not a fix. One addition from my own setup: for the CLI-tools row I've moved from pipx to uv tool install. Same per-tool isolation and the same ~/.local/bin layout, but installs are noticeably faster and uv tool upgrade --all handles updates in one shot. Worth a row in the table if you ever revisit it.