python config_error ai_generated true

error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install.

ID: python/pip-venv-externally-managed-environment

Also available as: JSON · Markdown · 中文
80%Fix Rate
90%Confidence
0Evidence
2024-01-30First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.10 active — — —
3.11 active — — —
3.12 active — — —

Root Cause

PEP 668: the OS marks its Python installation as externally managed (via EXTERNALLY-MANAGED marker), so pip refuses to install into system site-packages.

generic

中文

PEP 668：操作系统通过 EXTERNALLY-MANAGED 标记将其 Python 安装标记为外部管理，因此 pip 拒绝安装到系统 site-packages。

Workarounds

  1. 95% success 
    Create and use a virtual environment: `python -m venv .venv && source .venv/bin/activate && pip install foo`.
  2. 85% success 
    Install via the OS package manager if available: `sudo apt install python3-foo`, or use `pipx` for CLI apps: `pipx install foo`.

Dead Ends

Common approaches that don't work:

  1. 40% fail

    Overrides the safety guard and can break OS tooling that depends on system packages.

  2. 70% fail

    Still blocked by the externally-managed marker and risks system damage.