Python externally managed environment error

April 30, 2026 · View on GitHub

Playbook ID: python-externally-managed Category: build Severity: high Tags: python, pip, pep668, venv, environment, build

What this failure means

pip refused to install packages because Python 3.11+ on Ubuntu 24.04 or similar distributions enforces PEP 668, marking the system Python as externally managed. Direct pip installs are blocked to prevent conflicts with system packages.

Common log signals

externally managed environment
PEP 668
externally managed
Marked as externally managed
this environment is externally managed
remove.*system-wide pip
break-system-packages

Diagnosis

Python 3.11+ on Ubuntu 24.04, Fedora 38+, and other recent distributions enforce PEP 668, which marks the system Python as externally managed. Running pip install directly on the system Python fails with:

  • error: externally managed environment
  • This environment is externally managed
  • PEP 668: Marked as externally managed
  • Remove the system-wide pip installation first or equivalent.

Fix steps

  1. Use a virtual environment instead of system Python:

    python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

  2. Or use --break-system-packages flag (not recommended for production):

    pip install --break-system-packages -r requirements.txt

  3. In GitHub Actions, use the ubuntu-latest setup-python action which sets up pyenv:

    - uses: actions/setup-python@v5
  with:
    python-version: '3.12'

  4. For Docker containers, use the official Python slim images or create a venv in the Dockerfile:

    FROM python:3.12-slim
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

  5. Add EXTERNALLY_MANAGED marker file in the project to suppress the warning (development only):

    touch /opt/venv/EXTERNALLY_MANAGED

Validation

  • pip install -r requirements.txt completes successfully without PEP 668 errors.
  • pip list shows the expected installed packages.
  • The application imports and runs without import errors.

Likely files to inspect

  • requirements.txt
  • pyproject.toml
  • setup.py
  • Dockerfile

Run Faultline

faultline analyze build.log
faultline explain python-externally-managed
faultline workflow build.log --json --mode agent

Search phrases this page answers

  • Python externally managed environment error
  • Build: python externally managed environment error
  • this environment is externally managed
  • GitHub Actions python externally managed environment error
  • faultline explain python-externally-managed
  • Python python externally managed environment error

Generated from playbooks/bundled/log/build/python-externally-managed.yaml. Do not edit directly — run make docs-generate.