python install_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-error-externally-managed-environment

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

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.11 active — — —
3.12 active — — —
3.13 active — — —

Root Cause

PEP 668: Debian/Ubuntu (and Fedora) mark the system Python with an `EXTERNALLY-MANAGED` marker file so pip refuses to install into it, preventing breakage of OS-managed packages.

generic

中文

PEP 668：Debian/Ubuntu（及 Fedora）在系统 Python 中放置 `EXTERNALLY-MANAGED` 标记文件，使 pip 拒绝安装到系统环境，防止破坏操作系统管理的包。

Workarounds

  1. 95% success 
    Create and use a virtual environment (the intended workflow):

python3 -m venv .venv
source .venv/bin/activate
pip install <pkg>
  2. 85% success 
    Install via the OS package manager when a distro package exists:

sudo apt install python3-requests

For user-level installs without venv, use pipx for applications or `pip install --user` after creating a venv.

Dead Ends

Common approaches that don't work:

  1. 65% fail

    It works but writes into the OS-managed site-packages; a later apt upgrade can overwrite or break the package, and vice versa. Frequently corrupts the system Python.

  2. 60% fail

    Removing the marker bypasses the guard but does not solve the underlying problem; the next apt upgrade reinstalls the marker and can clobber your packages.