Skip to main content

How to Resolve Python PIP Error "WARNING: Ignoring invalid distribution -ip"

When using pip to install, upgrade, or list Python packages, you might encounter warnings like WARNING: Ignoring invalid distribution -ip (C:\path\to\site-packages) or similar variations with different prefixes (-, -ip, -jango, etc.). This warning indicates that pip found a directory within your Python environment's site-packages folder that looks like a package distribution but is malformed or incomplete, often resulting from an interrupted or failed package installation/uninstallation.

This guide explains how to locate and remove these invalid distribution directories to resolve the warning.

Understanding the Warning: Invalid Distributions​

Python packages, when installed, create directories within your environment's site-packages folder. These directories typically follow a naming convention (like requests/ or numpy/) and contain specific metadata files (METADATA, RECORD, etc.) that pip uses to manage the package.

The "Ignoring invalid distribution" warning means pip encountered a directory in site-packages whose name suggests it should be a package (often starting with a tilde ~ or a hyphen - followed by part of a package name), but it lacks the proper structure or metadata files. Pip recognizes it as corrupted or incomplete and ignores it, issuing the warning.

The Common Cause: Leftover Installation/Uninstallation Folders​

This usually happens when a pip install, pip uninstall, or pip upgrade process is interrupted unexpectedly (e.g., Ctrl+C, system crash, network error) or fails partway through. Pip might create temporary directories (often starting with ~) during the process or fail to completely remove a directory during uninstallation, leaving behind these "invalid distribution" remnants.

Solution: Locate and Delete the Invalid Distribution Folder(s)​

The solution is to manually remove these leftover folders from your site-packages directory.

Identifying the site-packages Directory​

The warning message itself typically provides the full path to the relevant site-packages directory. Look closely at the path shown in parentheses:

WARNING: Ignoring invalid distribution -ip (C:\Python310\lib\site-packages)
#                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  <-- This is the path
  • Windows: Often C:\Users\YourUser\AppData\Local\Programs\Python\PythonXX\Lib\site-packages, C:\PythonXX\Lib\site-packages, or inside a venv\Lib\site-packages folder if using a virtual environment.
  • macOS/Linux: Often /usr/local/lib/pythonX.Y/site-packages, /opt/homebrew/lib/pythonX.Y/site-packages, or inside venv/lib/pythonX.Y/site-packages for virtual environments.

You can also find it programmatically:

python -m site --user-site
# Or (for the general site-packages of the active python):
python -c "import site; print(site.getsitepackages())"

Identifying the Problematic Folder(s)​

Navigate to the site-packages directory identified in step 3.1. The warning message often gives a clue about the folder name:

  • Ignoring invalid distribution -ip (...): Look for folders starting with ~ip or -ip.
  • Ignoring invalid distribution - (...): Look for folders starting with ~ or -.
  • Ignoring invalid distribution requests (...): Look for folders starting with ~requests or -requests.

Often, these problematic folders will start with a tilde (~).

Deleting Manually (File Explorer / Finder)​

  1. Open the site-packages directory in your File Explorer (Windows) or Finder (macOS).
  2. Carefully look for folders whose names start with a tilde (~) or match the prefix mentioned in the warning (like -ip, -jango). These are typically the invalid ones.
  3. Select these specific folders (e.g., ~ip, ~-ip.dist-info, ~requests, ~-requests.dist-info).
  4. Permanently delete them (Shift+Delete on Windows, Cmd+Option+Delete or move to Trash and empty on macOS). Be careful not to delete valid package folders.

Deleting via Terminal (PowerShell, CMD, Bash)​

You can also delete these folders using the command line. Use these commands with extreme caution, ensuring you are in the correct site-packages directory first.

  1. Navigate to site-packages:

    cd C:\path\to\your\site-packages    # Windows (replace with actual path)
    # OR
    cd /path/to/your/site-packages      # Linux/macOS

  2. List Folders (Verify First!): Check which folders match the pattern before deleting.

    • PowerShell: Get-ChildItem -Directory ~*
    • CMD (Windows): dir /ad ~*
    • Bash (Linux/macOS): ls -d ~*
    note

    Adjust ~* if the warning indicated a different prefix like -ip*.

  3. Delete Matching Folders (Use with Caution!):

    • PowerShell: Remove-Item -Recurse -Force ~*
    • CMD (Windows): for /d %i in (~*) do rd /s /q "%i" (Run this directly in CMD. In a .bat script, use %%i instead of %i).
    • Bash (Linux/macOS): rm -rf ~*
    note

    Again, adjust ~* if needed and double-check the output of the listing command first.

After deleting the problematic folders, run your pip command again. The warning should be gone.

While deleting invalid folders is the direct fix, ensuring pip is up-to-date is always good practice, as newer versions might handle corrupted states more gracefully or provide clearer messages.

python -m pip install --upgrade pip
# Or
pip install --upgrade pip / pip3 install --upgrade pip

Conclusion​

The pip warning WARNING: Ignoring invalid distribution ... signals the presence of leftover, incomplete, or corrupted package directories within your site-packages folder, often named starting with a tilde (~).

The solution is to:

  1. Identify the correct site-packages directory from the warning message or using Python commands.
  2. Locate the specific invalid folder(s) mentioned or those starting with ~.
  3. Carefully delete these problematic folders using your file explorer or the appropriate terminal commands (rm -rf ~*, rd /s /q, Remove-Item).

Cleaning up these remnants resolves the warning and ensures pip operates on a clean environment state. Keeping pip updated is also recommended.

Table of Contents