Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

pip: error: externally-managed-environment and PEP 668

PEP 668 blocks pip from touching a distribution's Python. Why the marker file exists, which venv, pipx and apt paths replace it, and when --break-system-packages is honest.

~5 min readPython
#Python#pip#PEP 668#Linux
3D diagram of a sealed package crate with a lock and a cyan key outside, headline EXTERNALLY MANAGED

Introduction & Quick Summary

Symptom. pip install on a current Debian, Ubuntu, Fedora, or Homebrew Python stops with an error that never mentions a network or a missing package:

code
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.

Nothing is broken. The interpreter you are installing into belongs to the operating system, and the distribution has marked it off-limits for third-party packages.

Cause. PEP 668 defines a marker file, EXTERNALLY-MANAGED, written into the standard library directory of a system Python. pip 23.0.1 and later read that file and refuse to install into that environment, because a pip-installed package can overwrite a file owned by python3-apt or the distro's tooling, and the next apt upgrade either reverts it or breaks half of it. Debian 12, Ubuntu 23.04 and later (including 24.04 LTS), Fedora 38+, Linux Mint 21.3+, Homebrew's python@3.12 formula and several distro-based container images all ship the marker.

Fix. Install into an environment you own. For applications, a virtual environment: python3 -m venv .venv && . .venv/bin/activate. For command-line tools, pipx install. For libraries another system program imports, the distribution package (apt install python3-requests). --break-system-packages overrides the check deliberately, for one command or one image layer, and it is not the default answer.

Core Mechanics, Signatures & Reproducible Setup

The marker is a file, not a setting. pip resolves the standard library path of the running interpreter and looks for EXTERNALLY-MANAGED there:

bash
python3 - <<'PY' import os, sysconfig stdlib = sysconfig.get_path("stdlib") marker = os.path.join(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

On Ubuntu 24.04 that prints /usr/lib/python3.12/EXTERNALLY-MANAGED followed by the block pip echoes back. The file uses the INI-like format PEP 668 specifies, with an [externally-managed] section holding a human-readable Error= message; distributions customise that text, which is why the wording differs between Debian, Fedora and Homebrew while the failure is identical.

Three properties of the check matter in practice:

  • It keys on the interpreter, not on privileges. sudo pip install fails the same way, and so does pip run as root inside a Debian or Ubuntu container.
  • It only guards the default environment of that interpreter. A venv made by that interpreter is a different environment, so installs inside it are allowed even though the base interpreter is marked.
  • It can be overridden three ways, in increasing radius: the flag --break-system-packages, the variable PIP_BREAK_SYSTEM_PACKAGES=1, and the config key break-system-packages = true in pip.conf.

A minimal repro and fix:

bash
python3 -m pip install --dry-run requests # error: externally-managed-environment python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip .venv/bin/python -m pip install requests which python3 pip python3 -c "import sys; print(sys.prefix != sys.base_prefix)" # True inside a venv

That last expression is the most useful check when a shell, an IDE, or a CI step claims to be in a virtual environment but is not.

Key Comparison Table

Choosing the right escape from the marker is the whole decision:

ApproachWho owns the filesSurvives OS upgradesRight for
python3 -m venv .venvYou, per projectYesApplications, services, anything with a dependency file
uv venv / uv addYou, per projectYesSame, faster resolver and uv.lock
pipx install toolpipx, isolated per toolYesCLI tools such as black, poetry, httpie
apt install python3-xyzThe distributionYesLibraries other system packages import
pip install --user~/.local (often still blocked)UsuallyLegacy path; Debian patches user site off
--break-system-packagesThe distributionNo, apt fights youA throwaway container or an image layer you control
Deleting the markerThe distributionNoNever, unless apt no longer owns those paths

What each platform ships:

PlatformMarker sinceMessage points to
Debian 12 (bookworm)2023, Python 3.11apt install python3-xyz
Ubuntu 23.04 / 24.04 LTS2023python3 -m venv, apt install python3-full
Fedora 38+2023dnf install python3-xyz
Homebrew python@3.122023 formulapipx or a venv
python.org installernever—
python:3.12-slim (Docker Hub)never (built from source)—

The last row explains the usual confusion: the same pip install works in python:3.12-slim and fails on ubuntu:24.04, because the official Python images compile CPython themselves and never write the marker.

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Docker images that pip-install as root

A Dockerfile starting from ubuntu:24.04 or debian:12 hits the marker on the first RUN pip install. Use a virtual environment inside the image, not a global flag:

dockerfile
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"]

python:3.12-slim needs no venv; a distro image needs either this or apt for everything.

2. --user is not the escape it used to be

pip install --user requests used to avoid touching system paths. On Debian and Ubuntu the user site directory is patched off by default, and even where it is not, the marker check runs first, so the same error appears. Settle it with:

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

With ENABLE_USER_SITE false, --user only produces a second, more confusing failure.

3. CI that passes locally and fails on the runner

pip install -r requirements.txt succeeds on a macOS python.org install and fails on ubuntu-latest, whose Python comes from the distro. Make the interpreter explicit instead of trusting whichever pip resolves:

- 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

setup-python installs its own CPython and writes no marker, but pinning the venv keeps the workflow independent of the runner image.

4. When a build genuinely needs the system environment

Some images must install into the system interpreter: a single-layer image that runs distro Python, or a vendor installer that calls pip internally. Set the override once, with a reason next to it:

dockerfile
ENV PIP_BREAK_SYSTEM_PACKAGES=1 RUN pip install --no-cache-dir -r requirements.txt

For a one-off, prefer the visible flag over a baked environment:

bash
python3 -m pip install --break-system-packages --user ansible-core

An override with no comment is what breaks at the next base-image rebuild.

5. Recovering a system Python someone already broke

Do not delete directories by hand. Ask pip what it owns, then reinstall only the distribution's files:

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

--path lists what the distribution placed there, so apt --reinstall restores exactly those files and leaves ~/.local alone.

6. Editors and Jupyter keep the wrong interpreter

A notebook that cannot import a package pip just installed is a path problem, not a marker problem:

bash
jupyter kernelspec list python3 -m ipykernel install --user --name venv-312 --display-name "Python 3.12 (venv)"

The kernel must be the venv's interpreter; installing into .venv and selecting the system kernel gives ModuleNotFoundError while pip show insists the package exists.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Reading the note: line as the instruction. The ╰─> block above it names the supported paths; --break-system-packages is the escape hatch.
  • sudo pip install as a workaround. Same error, and where the marker is absent it writes files apt owns — the exact failure PEP 668 prevents.
  • Deleting EXTERNALLY-MANAGED. Works until the next apt upgrade overwrites those files, and the marker returns with the python3 package.
  • Bare pip instead of python3 -m pip. The check, the install target and the runtime import can involve three different Pythons.
  • Assuming python3-venv is installed. python3 -m venv fails with ensurepip is not available until apt install python3-venv; Ubuntu asks for python3-full. This happens before pip is involved.
  • PIP_REQUIRE_VIRTUALENV=true globally. pip then fails outside any venv with Could not find an activated virtual environment, which reads like the marker error but is your own guard.
  • Homebrew pip3 install --user. Homebrew's Python is marked and the user site mixes Apple's and Homebrew's frameworks; brew install pipx then pipx install <tool> is the supported route.
  • Layer caching hides a stale marker. A cached RUN pip install re-runs unchanged after the base image gains a marker, failing with no change on your side. Pin the base image digest when a build must reproduce.

Related tools. When the error arrives from CI, diff the two environments' variables with the environment file parser — PIP_*, PYTHONPATH and VIRTUAL_ENV usually differ in one line — and keep pip freeze output next to the Dockerfile that produced it: a requirements diff is easier to read than two image layers.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.