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.

This error means your system’s Python installation is protected by PEP 668. Starting with Python 3.11+ on Debian, Ubuntu, Fedora, and macOS (Homebrew), pip refuses to install packages globally to prevent you from breaking system packages that depend on specific Python library versions.

What causes this

Linux distributions and Homebrew use Python internally for system tools. If you pip install a package that upgrades or replaces a system dependency, you can break things like apt, dnf, or other OS utilities. PEP 668 introduced the EXTERNALLY-MANAGED marker file that tells pip “this Python installation is managed by the OS — don’t touch it.”

You’ll see this when:

• Running pip install <package> without a virtual environment on a modern OS
• Using pip install --user <package> on some distributions
• Running scripts that call pip globally in CI or Docker containers based on newer base images

Fix 1: Use a virtual environment (recommended)

This is the correct fix in almost every case. Virtual environments give you an isolated Python where you can install anything:

python3 -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

pip install requests flask   # Works fine now

When you’re done, deactivate to leave the venv. The packages stay in .venv/ and don’t touch your system Python.

Fix 2: Use pipx for CLI tools

If you’re installing a command-line tool (like black, ruff, httpie), use pipx — it creates an isolated venv per tool automatically:

# Install pipx first
sudo apt install pipx    # Debian/Ubuntu
brew install pipx         # macOS

# Install CLI tools
pipx install black
pipx install ruff
pipx install httpie

Each tool gets its own isolated environment, and the binary is added to your PATH.

Fix 3: Use the system package manager

For common packages, your OS might have them pre-packaged:

# Debian/Ubuntu
sudo apt install python3-requests python3-flask

# Fedora
sudo dnf install python3-requests python3-flask

This is the safest option for system-level scripts that need to run outside a venv.

Fix 4: Force install (not recommended)

You can override the protection, but this risks breaking your system:

pip install --break-system-packages requests

Or remove the marker file entirely:

sudo rm /usr/lib/python3.*/EXTERNALLY-MANAGED

⚠️ Don’t do this on a machine you care about. If you break system Python, tools like apt can stop working. This is only acceptable in throwaway Docker containers.

Fix 5: Fix it in Docker

If you hit this in a Dockerfile, create a venv or use the --break-system-packages flag:

# Option A: Use a venv
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install -r requirements.txt

# Option B: Override (acceptable in containers)
RUN pip install --break-system-packages -r requirements.txt

Related resources

• Python cheat sheet
• Python complete guide

How to prevent it

• Always use virtual environments for project work. Make it a habit — python3 -m venv .venv should be the first command in any new project.
• Use pipx for CLI tools you want available globally.
• In CI/CD, either use a venv or a Docker image that doesn’t have the EXTERNALLY-MANAGED marker (like python:3.12-slim).