Skip to content
Browse

/errors/pip/externally-managed-environment

pip error: externally-managed-environment (PEP 668)

The commands on this page have not been executed by our verification runner yet.updated 2026-10-20
tool
pip
exit code
1
versions
pip 23.0+, Debian 12+, Ubuntu 23.04+
os
linux, macos

pip fails with error: externally-managed-environment when you install into a Python interpreter that the operating system manages, such as /usr/bin/python3 on Debian 12 or Ubuntu 23.04 and later. The distribution marks that interpreter with an EXTERNALLY-MANAGED file (PEP 668) so that pip does not overwrite packages installed by apt. Install into a virtual environment instead.

Why it happens

Per the PEP 668 specification, an installer refuses to modify an interpreter when both are true:

  1. It is not running in a virtual environment (sys.prefix == sys.base_prefix).
  2. An EXTERNALLY-MANAGED file exists in the standard library directory, sysconfig.get_path("stdlib").

The rest of the message pip prints (for example "try apt install python3-xyz") comes from the Error= key of that file, so it differs between distributions.

Fix 1: use a virtual environment

bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install requests

On Debian and Ubuntu the venv module may need the python3-venv package first.

Fix 2: pipx for command-line tools

bash
pipx install httpie

pipx creates one environment per application and puts its commands on PATH.

Fix 3: the distribution package

bash
apt install python3-requests

Use this when a system service or script needs the library in the system interpreter.

FAQ

Is --break-system-packages safe?

It overrides the marker and installs into the system interpreter, where pip can overwrite files that the OS package manager owns. Avoid it outside throwaway containers.

Why don't I get this error inside a virtual environment?

The rule only applies outside a virtual environment. Inside one, sys.prefix differs from sys.base_prefix and pip installs normally.

Sources

Related pages

errors · pythonModuleNotFoundError: No module named '…'Python raises ModuleNotFoundError when the package is not installed for the interpreter that runs your code. Check sys.executable, then install with -m pip.compat · pythonPython version support and end-of-life datesWhich Python versions are supported in October 2026: 3.14 and 3.15 get bugfixes, 3.11 to 3.13 get security fixes only, 3.10 reached end of life on 2026-10-01.changes · pythonPython 3.14 to 3.15: what changes and what breaksUpgrading from Python 3.14 to 3.15: UTF-8 becomes the default encoding, lazy imports and frozendict arrive, and sqlite3, argparse and base64 change behaviour.