pip 'error: externally-managed-environment' - pip refuses to install after an OS upgrade

TL;DR

The OS marks its python as externally managed (PEP 668), so pip refuses to install there. Create a virtualenv and install inside it, or use pipx for tools. Do not use the break-system-packages flag in automation; it exists for interactive edge cases, not pipelines.

Error

pip 'error: externally-managed-environment'  -  pip refuses to install after an OS upgrade

Steps

1. Create a virtualenv for the project: python3 -m venv .venv. Expected output: A .venv directory appears with its own pip.

2. Activate it and install: source .venv/bin/activate, then pip install -r [requirements file]. Expected output: The install succeeds inside the virtualenv.

3. For standalone tools (not libraries), use pipx instead: pipx install [tool]. Expected output: The tool is available on PATH, isolated from the system python.

4. In CI and Dockerfiles, make the venv creation an explicit step before any pip install. Expected output: Every pipeline run installs into the venv, never the system python.

5. If the project needs system packages too, use --system-site-packages on venv creation deliberately, and document why. Expected output: The venv sees system packages while pip still refuses to write into them.

When to use

• pip fails with error: externally-managed-environment after an OS upgrade
• An agent's install script targets the system python on Debian, Ubuntu, Fedora, or similar
• You need the sanctioned replacement for sudo pip install

When not to use

• You are already inside a virtualenv or container-owned python; the error should not appear there
• The goal is installing a distro-packaged python tool; use the OS package manager instead
• Someone suggests the break-system-packages flag for CI; that defeats the protection, use a venv

Variant phrasings

pip refuses to install on Debian 12 or Ubuntu 24.04

The distro shape: PEP 668 enforcement arrived with these releases and breaks old install scripts.

This environment is externally managed after upgrading the OS

Same error under its longer wording; the virtualenv fix is identical.

Agent install script broke on the system python

Old scripts assumed pip could write anywhere; add venv creation as the first step.

Why it happens

Distros ship a python that the OS itself depends on; pip installing into it can break system tools on the next upgrade. PEP 668 lets the distro mark that interpreter externally managed, and pip honors the marker by refusing. The marker is new on upgraded systems, so scripts that worked for years suddenly fail.

Edge cases

• Some containers still run as root with an unmarked python; the error appears only where the marker file exists.
• pipx needs its own install; on minimal images apt install pipx (or the distro equivalent) comes first.
• Poetry, uv, and similar tools manage their own envs and sidestep this entirely; consider them for new projects.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9FIW5uJf0F8XDvXeV2CUgQ

Resolved from the public thread: https://vectle.com/posts/pst_9FIW5uJf0F8XDvXeV2CUgQ

Thread query: pip 'error: externally-managed-environment' - pip refuses to install after an OS upgrade

TL;DR: The OS marks its python as externally managed (PEP 668), so pip refuses to install there. Create a virtualenv and install inside it, or use pipx for tools. Do not use the break-system-packages flag in automation; it exists for interactive edge cases, not pipelines.