Fix: pip No Matching Distribution Found for <package>

The Error

You run pip install and get this:

ERROR: No matching distribution found for somepackage

Or with more context:

ERROR: Could not find a version that satisfies the requirement somepackage (from versions: none)
ERROR: No matching distribution found for somepackage

Sometimes it includes a version specifier:

ERROR: Could not find a version that satisfies the requirement somepackage==2.3.0 (from versions: 1.0.0, 1.1.0, 2.0.0, 2.1.0)
ERROR: No matching distribution found for somepackage==2.3.0

Or it lists available versions but none match your platform:

ERROR: Could not find a version that satisfies the requirement tensorflow==2.16.0 (from versions: none)
ERROR: No matching distribution found for tensorflow==2.16.0

Why This Happens

pip searches PyPI (or whichever package index you’re using) for a package that matches three things: the name you typed, the version you requested, and your platform (Python version, OS, and CPU architecture). If any of these don’t match, pip can’t find a distribution and gives this error.

The most common causes:

• Typo in the package name. PyPI package names are case-insensitive but must otherwise be exact. A single wrong character gives “no matching distribution.”
• The package doesn’t support your Python version. Many packages drop support for older Python versions or haven’t added support for the newest ones yet.
• The package doesn’t support your operating system or CPU architecture. Some packages only provide pre-built wheels for certain platforms (e.g., Linux x86_64 but not Windows ARM64).
• The version you requested doesn’t exist. You asked for a specific version that was never released, was yanked, or was removed.
• pip is outdated. Older pip versions don’t support newer wheel formats or metadata standards.
• You’re pointing at the wrong package index. A private index, mirror, or custom --index-url doesn’t have the package.
• PEP 668 externally-managed environment is interfering. On some systems, pip’s behavior changes when the system Python is marked as externally managed.
• The package is pre-release only. pip ignores pre-release versions by default.

Diagnostic Timeline: What Real Debugging Looks Like

The error message says “no matching distribution,” and the obvious read is that the package doesn’t exist. In practice, the package almost always exists — pip is just rejecting every version it sees for a reason it doesn’t print. Here is the order to chase that gets to the actual cause fastest.

First suspicion: the package doesn’t exist. Easy to confirm in one command: pip index versions somepackage. If the command returns a list of versions, the package exists and the problem is filtering, not absence. If it returns “no matching distribution” too, you have a typo or you’re hitting the wrong index — check pip config list for a private index-url that doesn’t mirror PyPI. In production CI failures, this is rarely the cause.

Second suspicion: outdated pip. Worth ruling out because the fix is one command. Run pip --version. A pip from 2021 or earlier can’t read newer wheel metadata or recognize the platform tags that 2024-era wheels publish. python -m pip install --upgrade pip and retry. If the error persists with current pip, you can rule out tooling and move on.

Third suspicion: the version you asked for was yanked. Check with pip index versions somepackage and look at the list. If the version is missing from the list, it was yanked or never released. Update the pin and move on.

The actual root cause in most production failures: a wheel tag mismatch you can’t see. Every wheel on PyPI has a tag like cp311-cp311-manylinux_2_17_x86_64.whl. pip filters wheels whose tags don’t intersect with the set your interpreter advertises. If your interpreter advertises cp312-cp312-musllinux_1_2_x86_64 (Alpine on Python 3.12) and every published wheel is cp311-cp311-manylinux2014_x86_64, pip rejects all of them without a useful message.

The discriminating command is pip debug --verbose (or pip install -vvv somepackage and watch the “Skipping” lines). It prints exactly which wheel tags your interpreter accepts. Compare those tags to what PyPI publishes for the package — the project’s “Download files” page on pypi.org shows every uploaded wheel with its tag. The mismatch is usually one of three patterns:

1. Python version mismatch. Wheels exist for cp311 and cp312, you’re on cp313. The package hasn’t shipped a 3.13 wheel yet. Fix: use pyenv or a venv to get a supported Python.
2. glibc vs musl. Wheels are manylinux_2_17_x86_64, you’re on Alpine which uses musl libc. Fix: switch to a glibc-based image (python:3.12-slim) or install build tools and build from source.
3. CPU architecture. Wheels are x86_64, you’re on aarch64 (ARM server) or arm64 (M-series Mac). Many small packages ship only x86_64. Fix: install build tools and let pip compile from sdist, or pick a different package.

Once you can read the tags pip is filtering by, every “no matching distribution” error becomes diagnosable in under thirty seconds. The cure is rarely “install something different” — it’s almost always changing the interpreter, the base image, or the wheel build constraints to produce tags that match what’s on PyPI.

Fix 1: Check for Typos in the Package Name

This is the most common cause, and the easiest to miss. PyPI package names don’t always match the import name in Python.

Common examples where the pip name differs from the import name:

Also watch for common typos:

# Wrong
pip install reqeusts
pip install flak
pip install djano
pip install num-py

# Correct
pip install requests
pip install flask
pip install django
pip install numpy

To verify a package name exists on PyPI, search for it:

pip index versions somepackage

Or check pypi.org directly in your browser. If the package you want is actually named something else, you’ll often find it by searching PyPI with the import name. For import-related errors after a successful install (a common follow-up problem), see Fix: ModuleNotFoundError in venv.

Common Mistake: Assuming the pip package name matches the Python import name. You type pip install sklearn and get “no matching distribution” because the correct name is scikit-learn. Similarly, import cv2 requires pip install opencv-python, and import yaml requires pip install PyYAML.

Fix 2: Check Your Python Version

Many packages require a minimum (or maximum) Python version. If your Python is too old or too new, pip won’t find a compatible distribution.

Check your Python version:

python --version
# or
python3 --version

Then check what Python versions the package supports. You can do this with:

pip index versions somepackage

This shows all available versions and their compatibility. You can also check the package’s page on PyPI — look for the “Requires-Python” field in the sidebar.

Example: Package doesn’t support Python 3.13 yet

You’re running Python 3.13, but the package only has wheels for up to Python 3.12:

ERROR: Could not find a version that satisfies the requirement somepackage==2.0.0
ERROR: No matching distribution found for somepackage==2.0.0

Fix: Use an older Python version. If you manage Python versions with pyenv:

pyenv install 3.12
pyenv local 3.12
pip install somepackage

Or create a virtual environment with a specific Python version:

python3.12 -m venv .venv
source .venv/bin/activate
pip install somepackage

If python3.12 is not available on your system, you may need to install it first. See Fix: python: command not found for instructions on installing specific Python versions.

Example: Package dropped support for Python 3.8

You’re running Python 3.8, but the latest version of the package requires Python 3.9+. pip will show:

ERROR: Could not find a version that satisfies the requirement somepackage>=2.0 (from versions: 1.0, 1.1, 1.2, 2.0, 2.1)
ERROR: No matching distribution found for somepackage>=2.0

Even though versions 2.0 and 2.1 exist, they require Python 3.9+, so pip filters them out.

Fix: Either upgrade Python or install an older version of the package that still supports your Python:

pip install somepackage==1.2

Fix 3: Check Your Platform and OS

Some packages only provide pre-built wheels for certain platforms. If there’s no wheel for your OS and CPU architecture, and the package has no source distribution (sdist), pip gives the “no matching distribution” error.

This is especially common with:

• Machine learning packages (TensorFlow, PyTorch) on non-standard architectures
• Windows ARM64 — many packages don’t provide ARM64 Windows wheels yet
• Alpine Linux — uses musl libc instead of glibc, so manylinux wheels don’t work
• macOS on Apple Silicon (M1/M2/M3/M4) — older package versions may not have arm64 wheels

Check your platform details:

python -c "import platform; print(platform.platform()); print(platform.machine())"

Check what pip considers your platform:

pip debug --verbose

This shows the compatible tags pip will accept (e.g., manylinux2014_x86_64, macosx_11_0_arm64, win_amd64).

Alpine Linux (musl libc)

If you’re running Python in an Alpine Docker container:

FROM python:3.12-alpine
RUN pip install pandas  # May fail — no musl wheels

Fix by switching to a glibc-based image:

FROM python:3.12-slim
RUN pip install pandas  # Works — manylinux wheels are compatible

Or install build dependencies and compile from source on Alpine:

FROM python:3.12-alpine
RUN apk add --no-cache gcc musl-dev python3-dev
RUN pip install pandas

macOS Apple Silicon

For older packages that don’t have arm64 wheels, you can try installing under Rosetta (x86_64 emulation):

arch -x86_64 pip install somepackage

This requires Rosetta 2 to be installed (softwareupdate --install-rosetta).

Fix 4: The Package Was Yanked or Removed

Package maintainers can yank specific versions from PyPI. A yanked version is hidden from normal installs but still exists. If you pin a yanked version, pip may not find it.

ERROR: Could not find a version that satisfies the requirement somepackage==1.5.2
ERROR: No matching distribution found for somepackage==1.5.2

Check which versions are available:

pip index versions somepackage

If the version you need is missing from the list, it was either yanked or never existed.

Fix: Use a different version. If you were pinning an exact version in requirements.txt, update the pin:

# Before
somepackage==1.5.2

# After — use the closest available version
somepackage==1.5.3

If a package was removed from PyPI entirely (rare, but it happens), you’ll need to find an alternative package or install from the source repository:

pip install git+https://github.com/author/[email protected]

Fix 5: Wrong Package Index URL

If you’ve configured a custom package index (via --index-url, PIP_INDEX_URL, or a pip.conf file), pip only searches that index. If the package isn’t in that index, you get the error.

Check if you have a custom index configured:

pip config list

Look for global.index-url or global.extra-index-url. Also check for environment variables:

echo $PIP_INDEX_URL
echo $PIP_EXTRA_INDEX_URL

And check for a pip.conf file (Linux/macOS: ~/.config/pip/pip.conf or ~/.pip/pip.conf; Windows: %APPDATA%\pip\pip.ini).

Fix: If you’re using a private index, add PyPI as an extra index so pip searches both:

pip install somepackage --extra-index-url https://pypi.org/simple/

Or install from PyPI directly, overriding any config:

pip install somepackage --index-url https://pypi.org/simple/

If you need packages from both a private index and PyPI, configure both in your pip.conf:

[global]
index-url = https://your-private-index.example.com/simple/
extra-index-url = https://pypi.org/simple/

For environment variable issues that might be silently rewriting PIP_INDEX_URL in CI, audit printenv | grep -i pip from inside the failing build environment — the value can come from a base image, a CI secret, or a pip.conf mounted into the container.

Fix 6: PEP 668 Externally-Managed Environment

On newer Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+) and macOS with Homebrew, the system Python is marked as externally managed. This can sometimes manifest as a “no matching distribution” error, especially when pip’s behavior is modified by the system.

More commonly you’ll see the explicit externally-managed-environment error, but if your system’s pip is patched or wrapped by the distribution, the error message can vary.

Fix: Use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install somepackage

Inside a virtual environment, pip operates without PEP 668 restrictions and can find and install packages normally. This is the recommended approach for all Python development regardless of the error you’re seeing.

Fix 7: Update pip

Older versions of pip don’t support newer packaging standards. If pip is outdated, it may fail to find packages that use modern metadata formats or wheel tags.

Check your pip version:

pip --version

Update pip:

python -m pip install --upgrade pip

If you’re in a virtual environment, update pip inside the venv:

source .venv/bin/activate
python -m pip install --upgrade pip

This is especially important for:

• Python 3.12+ — pip versions older than 23.x may have issues with the latest Python.
• Packages using PEP 517/518 builds — older pip versions don’t handle pyproject.toml-based builds.
• Packages with metadata 2.1+ — older pip can’t parse newer metadata formats.

If your pip is very old (below version 21), you may also need to update setuptools and wheel:

python -m pip install --upgrade pip setuptools wheel

Pro Tip: Run python -m pip install --upgrade pip before anything else. Older pip versions don’t recognize newer wheel formats, so they may fail to find packages that are actually available. A pip from 2021 can’t install wheels published with 2024 metadata standards.

Fix 8: Use —pre for Pre-Release Packages

By default, pip ignores pre-release versions (alpha, beta, release candidates). If the only available versions of a package are pre-releases, pip reports “no matching distribution.”

ERROR: Could not find a version that satisfies the requirement newpackage (from versions: 1.0.0a1, 1.0.0b2, 1.0.0rc1)
ERROR: No matching distribution found for newpackage

The versions exist, but pip skips them because they’re all pre-release.

Fix: Add the --pre flag to allow pre-release versions:

pip install --pre newpackage

Or pin a specific pre-release version directly:

pip install newpackage==1.0.0rc1

Pinning a specific pre-release version works without the --pre flag.

Caution: Pre-release packages may be unstable. Use them in production only if you understand the risks. This is common when testing upcoming versions of frameworks or when a package hasn’t made its first stable release yet.

Fix 9: Build from Source

If no pre-built wheel exists for your platform but the package has a source distribution (sdist), pip will try to build it. If the build fails, or if pip can’t find a compatible wheel and there’s no sdist, you get the “no matching distribution” error.

You can try to force building from source:

pip install somepackage --no-binary :all:

This tells pip to skip pre-built wheels and build from the source distribution. For this to work, you need the appropriate build tools installed.

Install build dependencies

# Ubuntu/Debian
sudo apt install build-essential python3-dev

# Fedora
sudo dnf install gcc python3-devel

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools from https://visualstudio.microsoft.com/visual-cpp-build-tools/

Some packages require additional system libraries. For example:

# For packages that need SSL (cryptography, etc.)
sudo apt install libssl-dev libffi-dev

# For packages that need database libraries
sudo apt install libpq-dev        # psycopg2
sudo apt install default-libmysqlclient-dev  # mysqlclient

# For packages that need image libraries
sudo apt install libjpeg-dev zlib1g-dev  # Pillow

# For packages that need XML libraries
sudo apt install libxml2-dev libxslt-dev  # lxml

If building from source still fails, check the package’s documentation for platform-specific installation instructions. Some packages, like TensorFlow, provide separate installation commands or URLs for different platforms.

You can also try installing directly from the package’s Git repository, which may have the latest build fixes:

pip install git+https://github.com/author/somepackage.git

For build failures that surface as pip exiting non-zero during wheel compilation, see Fix: pip could not build wheels.

Still Not Working?

Check if the package exists at all

Not everything is on PyPI. Some packages are hosted on custom indexes, installed from Git repositories, or distributed as local files.

# Search PyPI
pip index versions somepackage

# If the package is on a custom index
pip install somepackage --index-url https://custom-index.example.com/simple/

# If the package is on GitHub
pip install git+https://github.com/author/somepackage.git

# If you have a local .whl or .tar.gz file
pip install ./somepackage-1.0.0.tar.gz
pip install ./somepackage-1.0.0-cp312-cp312-manylinux_2_17_x86_64.whl

Network and firewall issues

If pip can’t reach PyPI at all, it may report “no matching distribution” instead of a clearer network error. Test connectivity:

pip install --verbose somepackage 2>&1 | head -50

Look for connection errors, timeouts, or SSL certificate issues in the verbose output. If you’re behind a corporate proxy:

pip install somepackage --proxy http://proxy.example.com:8080

Or set the proxy via environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
pip install somepackage

Conflicting version constraints

If you’re installing multiple packages with conflicting version requirements, pip may report “no matching distribution” for one of the transitive dependencies.

pip install packageA packageB
# ERROR: No matching distribution found for sharedlib>=2.0 (required by packageA)

This happens when packageA requires sharedlib>=2.0 but packageB requires sharedlib<2.0. No version of sharedlib can satisfy both.

Fix: Install the packages in separate virtual environments, or find compatible versions:

pip install packageA==1.2.0 packageB==3.4.0

Use pip install --dry-run (pip 22.2+) to preview what would be installed without actually doing it:

pip install --dry-run somepackage

Circular import unrelated to installation

If your package installs successfully but you get import errors afterward, the problem isn’t the installation — it’s a code issue. See Fix: Python circular import for help with circular import problems.

pip cache is stale

In rare cases, pip’s local cache can cause issues. Clear it:

pip cache purge
pip install somepackage

Or bypass the cache entirely:

pip install --no-cache-dir somepackage

Use verbose mode for diagnostics

When nothing else works, run pip in verbose mode to see exactly what’s happening:

pip install -vvv somepackage

This shows every URL pip checks, every version it considers and rejects, and the exact reason for each rejection. Look for lines containing “Skipping” or “not compatible” — they tell you exactly why pip is filtering out available versions.

Marker evaluation excluded every available wheel

PEP 508 environment markers (python_version, sys_platform, platform_machine) can exclude packages that exist and are otherwise compatible. If a requirement is written numpy; python_version<"3.13" and you’re on Python 3.13, pip silently skips that requirement entirely — and any transitive that needed it now fails with “no matching distribution” because the dependency tree has a gap. Inspect markers in your requirements.txt, pyproject.toml, and the failing package’s own metadata with pip show -v somepackage. Removing or widening the marker fixes it.

Hash mismatch in a constrained environment

If you’re using --require-hashes or installing from a pip-compile-generated requirements.txt with hashes, pip refuses any wheel whose hash isn’t in the file — even if a newer compatible wheel exists. The error often reads “no matching distribution” when the constraint file allows version X but pip can only find version Y. Regenerate the lockfile with pip-compile --upgrade (or your tool’s equivalent) so the hashes match the wheels currently on PyPI.

Mirror is out of sync with PyPI

Corporate PyPI mirrors (Artifactory, devpi, Nexus) sometimes lag PyPI by minutes to hours. If you released a package five minutes ago and CI pulls from a mirror, the mirror may not have indexed it yet. Confirm by curl -s https://your-mirror/simple/somepackage/ | head and see whether the file list contains the version you want. Either wait for the mirror to refresh, point at the mirror’s force-refresh endpoint, or fall back to --index-url https://pypi.org/simple/ for the affected install.

Related: Fix: python: command not found | Fix: ModuleNotFoundError in venv | Fix: pip could not build wheels | Fix: Python circular import