How do I prevent pip:EXTERNALLY_MANAGED_ENVIRONMENT in CI?

Use venvs by default for projects and CI. Avoid `sudo pip ...` on distro-managed systems. Document a team-standard Python toolchain and environment bootstrap process.

error: externally-managed-environment

Q: How can I manually validate pip:EXTERNALLY_MANAGED_ENVIRONMENT?

Confirm which Python pip is using: `python3 -m pip --version` (look at the Python path). Check whether you're already inside a venv: `python3 -c 'import sys; print(sys.prefix); print(sys.base_prefix)'` (in venv, `prefix != base_prefix`). If you need a system package, prefer the OS package manager instead of pip.

What This Environment Error Actually Means

Your OS Python is marked as "externally managed" (PEP 668), so pip refuses to modify the system environment outside a virtual environment.

Use the right Python environment

Preferred:install into a virtual environment: python3 -m venv .venv then activate and run python -m pip install ...

If you need globally installed Python apps, consider isolated installers like pipx (for CLIs) instead of system-wide pip installs.

If you truly must write to the system environment, use the distro-approved method (OS packages) or follow your distro guidance.

Last resort (unsafe):some distros allow overriding with --break-system-packages, use only if you understand the impact and preferably not on production machines.

Verify the Install Uses the Right Runtime

Activate your venv and run python -m pip install <package>, confirm the error is gone, and run python -m pip list and confirm the installed package is in the venv, not the system Python.

Check the active Python runtime

Confirm which Python pip is using:python3 -m pip --version (look at the Python path).

Check whether you're already inside a venv:python3 -c 'import sys; print(sys.prefix); print(sys.base_prefix)' (in venv, prefix != base_prefix).

If you need a system package, prefer the OS package manager instead of pip.

Why This Environment Blocks the Change

Usually this comes down to you're using the system Python that your OS package manager controls, you're running pip outside a venv while attempting to install into system site-packages, or a distro policy intentionally prevents system pip installs to preserve OS stability.

Examples

error: externally-managed-environment

Why pip blocks system installs

Some operating systems manage the system Python and installed packages via the OS package manager. When that Python environment is marked as externally managed (PEP 668), pip blocks installs/upgrades into the system site-packages to avoid breaking OS-managed packages. The safe default is to use a virtual environment (or another isolated install method) instead of system-wide installs.

Keep Runtime Environments Predictable

To prevent this, use venvs by default for projects and CI, avoid sudo pip ... on distro-managed systems, and document a team-standard Python toolchain and environment bootstrap process.

Docs and source code

github.com/pypa/pip/blob/25.3/src/pip/_internal/exceptions.py

pip defines the PEP 668 error as a DiagnosticPipError with reference externally-managed-environment. - GitHub

class ExternallyManagedEnvironment(DiagnosticPipError):
    """The current environment is externally managed.

    This is raised when the current environment is externally managed, as
    defined by `PEP 668`_. The ``EXTERNALLY-MANAGED`` configuration is checked
    and displayed when the error is bubbled up to the user.

    :param error: The error message read from ``EXTERNALLY-MANAGED``.
    """

    reference = "externally-managed-environment"

    def __init__(self, error: str | None) -> None:
        if error is None:
            context = Text(_DEFAULT_EXTERNALLY_MANAGED_ERROR)
        else:
            context = Text(error)
        super().__init__(
            message="This environment is externally managed",
            context=context,
            note_stmt=(
                "If you believe this is a mistake, please contact your "
                "Python installation or OS distribution provider. "
                "You can override this, at the risk of breaking your Python "
                "installation or OS, by passing --break-system-packages."
            ),
            hint_stmt=Text("See PEP 668 for the detailed specification."),
        )