error: externally-managed-environment

What This Error Means

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

How to Fix It

1. Preferred: install into a virtual environment: python3 -m venv .venv then activate and run python -m pip install ....
2. If you need globally installed Python apps, consider isolated installers like pipx (for CLIs) instead of system-wide pip installs.
3. If you truly must write to the system environment, use the distro-approved method (OS packages) or follow your distro guidance.
4. Last resort (unsafe): some distros allow overriding with --break-system-packages, use only if you understand the impact and preferably not on production machines.

Why It Happens

• 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.
• A distro policy intentionally prevents system pip installs to preserve OS stability.

How to Verify

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

Manual environment checks

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

Common CLI Output

error: externally-managed-environment

Why pip blocks system installs

1. Some operating systems manage the system Python and installed packages via the OS package manager.
2. 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.
3. The safe default is to use a virtual environment (or another isolated install method) instead of system-wide installs.

Prevention Tips

• 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.

Where This Can Be Triggered

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."),
        )