pip Error: Cannot Uninstall distutils Package Fix

Cannot uninstall a distutils installed project is pip's refusal to remove a package it can't safely track. The error ends with lines like Cannot uninstall 'six'. It is a distutils installed project and thus we cannot accurately determine which files belong to it. Your upgrade stops halfway: the old version stays, the new one never lands, and requirements stay unmet.

It shows up in four everyday spots. An OS-managed package like python3-six was placed by apt, so pip owns no uninstall record. A project install went to system Python instead of a venv, mixing owners in one directory. A past --ignore-installed run left two copies shadowing each other. A modern Debian or Fedora ships PEP 668's EXTERNALLY-MANAGED marker, and pip now refuses the whole operation up front.

The fix is never forcing the uninstall. You'll leave system files alone, create a virtualenv, and install your versions where pip owns everything. This guide shows how to confirm the owner, build the venv, and pick the safe alternative for each case.

OS-Managed Packages: Why pip Refuses Instead of Guessing

OS-managed packages are files your Linux distribution placed and tracks, and pip knows it shouldn't touch them. You'll install python3-six through apt and the files land in /usr/lib/python3/dist-packages with dpkg recording each one. When pip later tries upgrading six, it finds a distutils-era install with no reliable file manifest — old setup.py installs never wrote the RECORD pip needs. Rather than guessing which files are safe, pip aborts with the distutils error. That refusal protects apt's database: deleting a file apt claims breaks future upgrades and can remove modules OS tools import at boot.

Confirm ownership before acting. You'll run apt list --installed | grep six to see the OS claim, and pip show six to see pip's view — a Location inside dist-packages plus thin metadata confirms the split. The fix is leaving those files untouched and installing your version where you own everything. You'll create a venv and run pip there, giving the new six a private directory with full RECORD metadata and clean uninstalls forever.

Treat system site-packages as read-only museum storage. You'll look but never rearrange, and every project gets its own room. Teams that adopt this rule stop seeing the distutils error entirely, since pip inside a venv never meets a file it doesn't own.

import sys

# Show which Python owns your packages before installing anything
print("exe:", sys.executable)
print("prefix:", sys.prefix)
print("is venv:", sys.prefix != sys.base_prefix)
for path in sys.path:
    if "site-packages" in path or "dist-packages" in path:
        print("pkgs:", path)

Virtualenv Instead: A Private Directory pip Fully Owns

A virtualenv ends this error class by giving pip a directory it fully owns. You'll run python3 -m venv .venv and get a private interpreter plus a private site-packages where every install writes complete metadata. Upgrades there never meet OS files, so the distutils complaint can't fire — there's simply nothing foreign to trip on. Activation with source .venv/bin/activate points pip and python at that directory, and pip -V confirms the path before you install a thing.

Make the venv the only place project packages live. You'll keep a requirements.txt per project, install with pip install -r requirements.txt after activating, and commit the file — never the venv directory. For CLI tools like black or ruff, you'll use pipx instead, which builds one venv per tool and links just the binary. System Python then serves only the OS, exactly as Debian and Fedora intend.

Enforce the habit so future you can't slip. You'll export PIP_REQUIRE_VIRTUALENV=true in your shell profile, making bare pip outside a venv fail with a clear message. That one guard has saved more fleets than any wiki page, since it converts a 52-minute boot outage into a 5-second reminder at install time. Document the four commands in onboarding so every machine matches from day one.

import os
import subprocess
import sys

# Build the safe home for project packages in 3 commands
print("system pip:", subprocess.run(
    [sys.executable, "-m", "pip", "-V"],
    capture_output=True, text=True, timeout=30).stdout.strip())
venv_dir = "/tmp/demo-venv"
print("create:", f"{sys.executable} -m venv {venv_dir}")
print("activate:", f"source {venv_dir}/bin/activate")
print("guard:", "PIP_REQUIRE_VIRTUALENV=true blocks bare installs")
print("pip present:", os.path.basename(sys.executable))

--ignore-installed Risks: Two Copies and Imports That Flip

The --ignore-installed flag bulldozes the guard by installing a second copy alongside the first, and you'll inherit version shadowing. You'll run pip install --ignore-installed six and now two six.py files exist — the OS one in dist-packages and yours in site-packages or user site. Imports resolve by sys.path order, so Monday loads your copy and Tuesday's cron job loads the OS one, producing crashes that vanish when a coworker reproduces them. Debugging by version string lies too, since pip show reports one copy while Python imports the other.

Confirm shadowing with the file path, not the version. You'll run python3 -c "import six; print(six.__file__)" and compare against pip's Location — a mismatch proves two copies. The fix is removing the shadow from user site only, never touching system files, then installing the pinned version once inside the venv. That single owned copy makes imports deterministic across shells, cron, and containers.

Reserve the flag for venv interiors. You'll use it there when a base image pre-seeds a stale wheel, and nowhere else. Code review should treat bare --ignore-installed on system Python like sudo pip: a red flag that fails the build until replaced with a venv install.

import six

# Pin down which copy of a package Python actually imports
print("file:", six.__file__)
print("version:", six.__version__)

# Shadowing check: user-site copy wins over system copy by path order
import site
print("user site:", site.getusersitepackages())
print("rule: first path hit wins; duplicates mean unpredictable imports")

PEP 668 Externally-Managed: The Guardrail You Should Keep

PEP 668 made the protection explicit with the EXTERNALLY-MANAGED marker file. You'll find it at /usr/lib/python3.11/EXTERNALLY-MANAGED on Debian 12, Ubuntu 23.04+, and Fedora 38+, carrying a message that this interpreter belongs to the OS. Modern pip reads it and refuses bare installs with an externally-managed-environment error instead of the older distutils wording. Same intent, louder voice: the refusal now arrives before any download, so you waste seconds instead of a half-upgraded system.

Read the marker rather than overriding it. You'll cat the file to confirm the OS claim, then choose the sanctioned path: venv for projects, pipx for apps, apt for system libraries. The --break-system-packages flag exists but amounts to signing a waiver — pip obeys and the corruption risk returns in full. You'll never set it on hosts, images, or shared runners, since one waiver in a Dockerfile propagates to every container built from it.

Standardize on the trio and document it once. You'll write the repo guide as three lines: apt for system, venv for projects, pipx for tools. New hires then never meet either error, and the 52-minute boot outage stays a war story instead of a quarterly event.

from pathlib import Path

# Detect the PEP 668 guard marker before fighting pip
candidates = sorted(Path("/usr/lib").glob("python3*/EXTERNALLY-MANAGED"))
print("markers:", [str(p) for p in candidates] or ["none found"])
for marker in candidates[:2]:
    print("---", marker)
    print(marker.read_text()[:400])

Why sudo pip Worsens Everything: Root Can't Fix Ownership

Running sudo pip escalates a blocked upgrade into system damage. You'll type sudo to overpower the refusal, and pip — now root — happily overwrites files in /usr/lib/python3/dist-packages that apt recorded and cloud-init imports. The install reports success, CI passes since containers already built, and weeks later a reboot or an apt upgrade detonates: cloud-init crashes on the bumped six API, apt refuses with checksum mismatches, and 9 fresh hosts fail boot while old ones look healthy. Root didn't fix ownership; it just let pip vandalize with privileges.

Audit for past damage with package eyes. You'll compare pip list against apt list --installed for twin-owned names, and inspect /usr/local/lib versus dist-packages for root-stamped shadows. Recovery means restoring OS files via apt (apt install --reinstall python3-six) and moving project deps into a venv — never deleting system files by hand to settle the difference. Hand-deletion orphans apt records and breaks the next three upgrades instead of one.

Ban the pattern where it breeds. You'll add a CI grep failing on sudo pip and --break-system-packages, and pin base-image system packages through apt only. Teams that enforce this spend their incident budget on real bugs instead of rebuilding hosts that a one-line Dockerfile change bricked.

Safe Upgrade Workflow: venv, Pin, Verify, Repeat

Lock in the safe workflow once and the error never returns. You'll create the venv with python3 -m venv .venv, activate it, upgrade pip inside, and install from a pinned requirements.txt. You'll verify with pip -V showing the .venv path and python -c "import sys; print(sys.prefix)" pointing inside it. Every teammate repeats the same 4 commands, so environments match and the distutils guard never fires — there's no foreign file in the venv to argue over.

Separate the three install kinds for good. You'll reach for apt when the OS needs a library, the venv's pip when the project needs one, and pipx when you need a standalone tool. You'll record each in its own manifest — apt pins in the image file, pip pins in requirements.txt — so upgrades stay scoped. A six bump then touches one venv's lockfile instead of nine hosts' boot path.

Teach the guard as a feature, not friction. You'll tell new hires pip refused in order to save the fleet, and show the venv flow in onboarding. Teams that frame it that way get zero sudo-pip incidents a year, while teams that frame it as annoyance collect waivers until the next 52-minute outage. Rerun pip -V after every activation change, since one stale shell can reinstall into the wrong prefix silently.