Pip's "error: externally-managed-environment" and PEP 668

What it is

error: externally-managed-environment is pip's response (pip 23.0 and later) to finding an EXTERNALLY-MANAGED marker file in the target Python installation's standard-library directory; the block below it begins × This environment is externally managed. Outside a virtual environment it blocks pip install --user as well. PEP 668 defines that marker: a distributor (a Linux distribution, but also conda or a similar system) places it to declare that this particular Python install is managed by something other than pip, so pip must not install, upgrade or remove packages into it directly. The Python Packaging User Guide's specification page documents the same marker and the recommended installer behaviour. The message is pip's, not Python's; the marker file itself may embed the distributor's own suggested remedy text, which is worth reading before applying a generic fix.

Why it matters

Before PEP 668, a pip install outside a virtual environment could silently overwrite or shadow a package that the OS's own package manager also manages and depends on, breaking system tools built against a specific version. The marker turns that into a loud failure instead of a quiet corruption, at the cost of breaking scripts and container images that assumed unrestricted global installs.

How to apply

• Diagnose: find the marker with python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))" and look for EXTERNALLY-MANAGED in that directory; its contents often name the distro's preferred fix.
• Fixes, least to most invasive:
  1. Use a virtual environment for the project: python3 -m venv .venv && source .venv/bin/activate && pip install ... — isolates installs from the managed interpreter entirely, and is the fix PEP 668 is designed to push toward.
  2. Install a standalone CLI tool with pipx install <tool>, which creates its own isolated environment per tool.
  3. Install the distro's own packaged version with its package manager (e.g. apt install python3-<name>) when one exists.
  4. Only inside a disposable, single-purpose environment being built for one job (a throwaway container image, a CI step that never reuses the interpreter afterward), override with pip install --break-system-packages ... (pip 23.0.1+, or PIP_BREAK_SYSTEM_PACKAGES=1) — an unsafe last resort that can overwrite files the OS package manager owns, not a default flag to add everywhere.
• Unsafe/misleading: deleting the EXTERNALLY-MANAGED file. It silences the warning without isolating anything, and a distro upgrade can simply put it back.

Pitfalls

• Adding --break-system-packages to a shared or long-lived host "to stop the error" turns every future install into the exact conflict the marker exists to prevent.
• Assuming the marker is a pip bug; it is deliberate distro policy that pip is honoring.