What does pip:DISTUTILS_UNINSTALL_BLOCKED mean?

pip will not uninstall the package because distutils or OS packaging installed it without metadata that safely maps files to remove.

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

Q: 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.

Q: 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.

Fix it fast

Most likely: The package was installed with legacy distutils or by another installer, so pip cannot safely determine the files it would remove.

1. Confirm this is your error

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.

2. Check the cause

python -m pip show <pkg>
python -m pip --version
python -m pip check

3. Apply the safe fix

# If it is system-managed, remove or update it with the system package manager.

# If this is a project dependency, create a clean venv and install the project there.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

# If you must keep this environment, prefer rebuilding it over manually deleting legacy-installed files.

4. Verify it works

python -m pip show <pkg>
python -m pip check

Don't use unsafe shortcuts

Do not force a partial uninstall of a distutils-installed package from system Python.
Do not mix OS package manager packages and pip-managed project dependencies in the same environment.
Do not delete files by hand from site-packages unless rebuilding the environment is impossible.

What This Error Means

Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.

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

Usually this comes down to 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, or you're attempting to use pip to manage system Python packages.

Verify the Fix

After uninstalling via the correct manager, run python -m pip show <pkg> and confirm it's gone, and 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.

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.

Prevent It From Coming Back

To prevent this, avoid installing project dependencies into system Python, use venvs and dependency lock files to keep environments reproducible, and avoid mixing package managers within the same environment.

Docs and source code

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