pip "WARNING: Ignoring invalid distribution" in CI
pip found a directory in site-packages whose name starts with ~ (a tilde), which is the artifact of an interrupted or partial uninstall. pip cannot read it as a valid distribution and warns on every command.
What this error means
Nearly every pip command prints "WARNING: Ignoring invalid distribution -X (/path/site-packages)". Installs may still work, but the warning signals a corrupted package directory.
pip
WARNING: Ignoring invalid distribution -umpy (/usr/lib/python3.12/site-packages)
WARNING: Ignoring invalid distribution -ip (/usr/lib/python3.12/site-packages)Common causes
An interrupted install or uninstall
A cancelled or OOM-killed pip operation left a ~ame rename directory that pip later cannot parse.
A cached/persisted environment carried the corruption forward
Reusing a cached site-packages directory across runs preserves the stray ~ directories.
How to fix it
Remove the stray tilde directories
- Identify the site-packages path from the warning.
- Delete the directories whose names begin with a tilde.
- Re-run pip; the warning should be gone.
Terminal
python -c "import site,glob,os; [print(p) for p in glob.glob(os.path.join(site.getsitepackages()[0], '~*'))]"
# then remove them
find "$(python -c 'import site;print(site.getsitepackages()[0])')" -maxdepth 1 -name '~*' -exec rm -rf {} +Use a clean virtual environment
Create a fresh venv per run so no corrupted state persists.
Terminal
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txtHow to prevent it
- Use a fresh virtual environment per CI run.
- Avoid caching the full site-packages directory; cache the wheel/download dir instead.
- Do not interrupt pip mid-install in scripts.
Frequently asked questions
What causes ""Ignoring invalid distribution""?
A cancelled or OOM-killed pip operation left a ~ame rename directory that pip later cannot parse.
How do I fix "Ignoring invalid distribution"?
Remove the stray tilde directories
Related guides
pip "Cannot install X and Y because these have conflicting dependencies" in CIFix pip "Cannot install X and Y because these have conflicting dependencies" in CI - two direct requirements…
Python "ModuleNotFoundError: No module named setuptools" in CIFix "ModuleNotFoundError: No module named 'setuptools'" in CI - a build or script needs setuptools but the in…
Python venv activate not persisting across steps in CIFix a Python venv that activates in one CI step but is gone in the next - each step runs in a fresh shell, so…