Which PIP versions are affected by pip:DISTUTILS_UNINSTALL_BLOCKED?

All pip versions that protect against partial uninstalls.

How can I manually validate pip:DISTUTILS_UNINSTALL_BLOCKED?

Check where the package lives: `python -m pip show ` (Location). Decide whether the package is system-managed or project-managed (venv). If you need to remove it from system Python, use the system package manager.

How do I prevent pip:DISTUTILS_UNINSTALL_BLOCKED in CI?

Avoid installing project dependencies into system Python. Use venvs and dependency lock files to keep environments reproducible. Avoid mixing package managers within the same environment.

RepoFlow | ERROR: Cannot uninstall '<pkg>'. It is a distutils installed project ...

What This Error Means

pip refuses to uninstall a package that was installed via distutils/OS tooling without reliable metadata, because it can't safely determine which files to remove.

How to Fix It

If the package is system-owned, uninstall it via your OS package manager instead of pip.
If the package is project dependency, create a clean venv, install there, and stop modifying system Python.
If you need to keep the environment but clean it, consider rebuilding the environment rather than trying to surgically uninstall distutils-era packages.

Why It Happens

The package was installed by a system package manager or another installer that didn't create pip-managed metadata.
The package metadata is incomplete or corrupted.
You're attempting to use pip to manage system Python packages.

How to Verify

After uninstalling via the correct manager, run python -m pip show <pkg> and confirm it's gone.
Run python -m pip check to confirm no broken dependencies remain.

Manual ownership checks

Check where the package lives: python -m pip show <pkg> (Location).
Decide whether the package is system-managed or project-managed (venv).
If you need to remove it from system Python, use the system package manager.

Common CLI Output

ERROR: Cannot uninstall 'PyYAML'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall.

Why distutils installs are hard to uninstall

pip prefers dist-info metadata that records installed files and versions.
distutils-era installs can lack complete metadata, making it risky to uninstall without leaving orphan files or removing unrelated files.
pip blocks the uninstall rather than performing a potentially destructive partial uninstall.

Prevention Tips

Avoid installing project dependencies into system Python.
Use venvs and dependency lock files to keep environments reproducible.
Avoid mixing package managers within the same environment.

Where This Can Be Triggered

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

pip blocks uninstalls when it detects a distutils-era install without reliable metadata, it raises LegacyDistutilsInstall rather than risk a partial uninstall. - GitHub

class LegacyDistutilsInstall(DiagnosticPipError):
    reference = "uninstall-distutils-installed-package"

    def __init__(self, *, distribution: BaseDistribution) -> None:
        super().__init__(
            message=Text(f"Cannot uninstall {distribution}"),
            context=(
                "It is a distutils installed project and thus we cannot accurately "
                "determine which files belong to it which would lead to only a partial "
                "uninstall."
            ),
            hint_stmt=None,
        )