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.

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:
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:
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])
PYOn 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 installfails 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 variablePIP_BREAK_SYSTEM_PACKAGES=1, and the config keybreak-system-packages = trueinpip.conf.
A minimal repro and fix:
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 venvThat 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:
| Approach | Who owns the files | Survives OS upgrades | Right for |
|---|---|---|---|
python3 -m venv .venv | You, per project | Yes | Applications, services, anything with a dependency file |
uv venv / uv add | You, per project | Yes | Same, faster resolver and uv.lock |
pipx install tool | pipx, isolated per tool | Yes | CLI tools such as black, poetry, httpie |
apt install python3-xyz | The distribution | Yes | Libraries other system packages import |
pip install --user | ~/.local (often still blocked) | Usually | Legacy path; Debian patches user site off |
--break-system-packages | The distribution | No, apt fights you | A throwaway container or an image layer you control |
| Deleting the marker | The distribution | No | Never, unless apt no longer owns those paths |
What each platform ships:
| Platform | Marker since | Message points to |
|---|---|---|
| Debian 12 (bookworm) | 2023, Python 3.11 | apt install python3-xyz |
| Ubuntu 23.04 / 24.04 LTS | 2023 | python3 -m venv, apt install python3-full |
| Fedora 38+ | 2023 | dnf install python3-xyz |
Homebrew python@3.12 | 2023 formula | pipx or a venv |
| python.org installer | never | — |
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:
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:
python3 -m site --user-site
python3 -c "import site; print(site.ENABLE_USER_SITE)" # False on Debian/UbuntuWith 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/pytestsetup-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:
ENV PIP_BREAK_SYSTEM_PACKAGES=1
RUN pip install --no-cache-dir -r requirements.txtFor a one-off, prefer the visible flag over a baked environment:
python3 -m pip install --break-system-packages --user ansible-coreAn 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:
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:
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-packagesis the escape hatch. sudo pip installas a workaround. Same error, and where the marker is absent it writes filesaptowns — the exact failure PEP 668 prevents.- Deleting
EXTERNALLY-MANAGED. Works until the nextapt upgradeoverwrites those files, and the marker returns with thepython3package. - Bare
pipinstead ofpython3 -m pip. The check, the install target and the runtime import can involve three different Pythons. - Assuming
python3-venvis installed.python3 -m venvfails withensurepip is not availableuntilapt install python3-venv; Ubuntu asks forpython3-full. This happens before pip is involved. PIP_REQUIRE_VIRTUALENV=trueglobally. pip then fails outside any venv withCould 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 pipxthenpipx install <tool>is the supported route. - Layer caching hides a stale marker. A cached
RUN pip installre-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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
iter() is what every for loop calls first. Learn single-pass behavior, the sentinel form for chunked reads, and how custom iterators define __next__.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
kafka-python is pure Python; confluent-kafka wraps librdkafka. Compare APIs, throughput, error handling, and pick the client that fits your service.
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.