error pip 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. If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. If you wish to install a non-Debian packaged Python application, it may be easiest to use pipx install xyz, which will manage a virtual environment for you. Make sure you have pipx installed. See /usr/share/doc/python3.11/README.venv for more information.

ID: pip/pep-668-externally-managed-environment

Also available as: JSON · Markdown · 中文
92%Fix Rate
88%Confidence
1Evidence
2023-04-23First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
pip 23.0+ active — — —
Debian 12 active — — —
Ubuntu 23.04+ active — — —
Python 3.11 active — — —

Root Cause

Debian/Ubuntu systems mark the system Python installation as externally managed (via PEP 668) to prevent pip from overwriting packages managed by the system package manager, but users attempt to install packages globally with pip outside a virtual environment.

generic

中文

Debian/Ubuntu 系统将系统 Python 安装标记为外部管理（根据 PEP 668），以防止 pip 覆盖由系统包管理器管理的包，但用户尝试在虚拟环境外部全局使用 pip 安装包。

Official Documentation

https://packaging.python.org/en/latest/specifications/externally-managed-environments/

Workarounds

  1. 95% success Create and use a virtual environment: python3 -m venv myenv && source myenv/bin/activate && pip install <package> 
    Create and use a virtual environment: python3 -m venv myenv && source myenv/bin/activate && pip install <package>
  2. 90% success Use pipx for installing CLI applications: pipx install <package> 
    Use pipx for installing CLI applications: pipx install <package>
  3. 85% success Install the package via apt if available: apt install python3-<package> 
    Install the package via apt if available: apt install python3-<package>

中文步骤

  1. 创建并使用虚拟环境：python3 -m venv myenv && source myenv/bin/activate && pip install <package>
  2. 使用 pipx 安装 CLI 应用程序：pipx install <package>
  3. 通过 apt 安装包（如果可用）：apt install python3-<package>

Dead Ends

Common approaches that don't work:

  1. Running pip with --break-system-packages flag 30% fail

    This flag bypasses the protection but may break system tools that depend on specific package versions, leading to system instability or broken apt packages.

  2. Removing the EXTERNALLY-MANAGED file from /usr/lib/python3.x/ 40% fail

    Deleting the marker file permanently disables the protection, but future system updates may restore it, and it violates the distribution's design intent.

  3. Installing packages with sudo pip install 60% fail

    Running pip as root in a system environment can corrupt system Python packages, cause permission conflicts, and is strongly discouraged by Python packaging guidelines.