OSPython Error

pip externally managed

error: externally-managed-environment

Traceback

terminal

Traceback (most recent call last):
  File "main.py", line 3, in <module>
    # This environment is externally managed
error: externally-managed-environment

What causes this error

The system Python is marked as externally managed by the OS package manager (PEP 668). Direct pip installation is blocked to prevent breaking system tools.

How to fix it

Always use virtual environments: `python3 -m venv myenv`. Use `pipx` for CLI tools. Install system Python packages via the OS package manager. The `--break-system-packages` flag exists but is strongly discouraged.

Code that causes this error

Broken

pip install flask
# error: externally-managed-environment
# This environment is externally managed

Fixed code

Fixed

# Create a virtual environment:
python3 -m venv myproject
source myproject/bin/activate
pip install flask

# For CLI tools, use pipx:
pipx install black
pipx install mypy

About pip externally managed

This error was introduced by PEP 668 and appears on Linux distributions (starting with Debian 12/Ubuntu 23.04, Fedora 38+, Arch Linux) that mark their Python installation as 'externally managed.' This means the system Python is managed by the OS package manager (apt, dnf, pacman), and pip should not install packages into it to avoid breaking system tools. The rationale is that system Python packages (installed via apt/dnf) and pip packages can conflict, leading to broken system utilities. The solution is to always use virtual environments for your projects, which creates an isolated Python environment with its own packages.

If you need a system-wide tool, use `pipx` which installs each tool in its own isolated environment. For system packages, use the OS package manager: `apt install python3-requests` instead of `pip install requests`.

Common scenarios

Running scripts without sufficient file system permissions

Connecting to servers that are not running or are unreachable

Installing Python packages without proper environment setup

Running out of disk space or file descriptors during I/O operations