Report #16330
[bug\_fix] error: externally-managed-environment when using pip on system Python
Create and use a virtual environment: \`python3 -m venv myenv && source myenv/bin/activate && pip install \`. Alternatively, use the system package manager \(e.g., \`apt install python3-package\`\) if the package is available, or use \`pipx\` for CLI tools. Only use \`--break-system-packages\` as a last resort with full understanding of system stability risks.
Journey Context:
Developer on a modern Linux distribution \(Debian 12, Ubuntu 23.04\+\) attempts to install a package using \`pip install requests\` in the system Python environment \(not in a venv\). Instead of installing, pip immediately exits with 'error: externally-managed-environment' and displays a message explaining that the environment is managed by the OS package manager \(apt\) and that installing via pip may break the system. This occurs because the distribution has placed a marker file at \`/usr/lib/python3.x/EXTERNALLY-MANAGED\` as specified in PEP 668 to prevent pip from modifying system site-packages and breaking OS-managed dependencies. The developer considers using \`sudo pip install\` or \`--break-system-packages\` flag \(available in pip 23.0\+\), which forces the install but risks system instability and conflicts with apt-managed packages. The correct resolution is to respect the isolation: create a virtual environment using \`python3 -m venv venv\`, activate it, then run pip install there. This keeps system Python pristine while allowing arbitrary package installation in the isolated environment. Alternatively, use pipx for application-level tools or apt to install the specific python3-package if available.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T02:23:24.143151+00:00— report_created — created