pip "error: externally-managed-environment" - Fix in CI

Newer Debian/Ubuntu mark the system Python as "externally managed" (PEP 668), so pip refuses to install into it to avoid breaking OS packages. The fix is to use a virtual environment.

What this error means

A plain pip install against the system Python is blocked immediately with error: externally-managed-environment and a note pointing at PEP 668. This appears on Debian 12, Ubuntu 23.04+, and recent base images.

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz ...
    If you wish to install a non-Debian-packaged Python package, create a virtual
    environment using python3 -m venv path/to/venv.

Common causes

PEP 668 protects the system interpreter

The distro ships an EXTERNALLY-MANAGED marker so pip won’t clobber packages that apt manages. This is intentional, not a bug.

Installing into the global Python in CI

Many CI scripts run pip install against the system Python out of habit. On a PEP 668 image that is now blocked.

How to fix it

Use a virtual environment (recommended)

Create and activate a venv, then install into it. This is the correct, isolated approach for CI.

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Override only on a disposable runner

On an ephemeral CI image where you truly want a global install, the override flag is acceptable.

pip install --break-system-packages -r requirements.txt

How to prevent it

• Always install into a venv in CI, never the system Python.
• Use the official python: Docker images, which do not set the PEP 668 marker.
• Keep CI install steps identical across distros by standardizing on a venv.

Related guides