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. 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 Three properties decide most arguments about it:
- It keys on the interpreter, not on privileges.
sudo pip installfails identically, and so does pip running as root inside adebian:12orubuntu:24.04container. - 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"] 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 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 --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 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 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" -
python3 -m venvcan fail withensurepip is not availablebefore pip is involved — installpython3-venv, which Ubuntu callspython3-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=trueproduces "Could not find an activated virtual environment", which reads like the marker error but is your own guard. - Homebrew:
brew install pipxthenpipx install <tool>; mixing Apple's and Homebrew's frameworks through--useris the failure mode to avoid.
What not to do
- Do not
sudo pip installto get past it. Same error, and where the marker is absent it writes filesaptowns — exactly what PEP 668 prevents. - Do not delete
EXTERNALLY-MANAGED. The nextapt upgraderestores it along with thepython3package. - Do not read
--break-system-packagesas 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.


