Fix: pip No Matching Distribution Found for <package>

The Distribution That pip Says Does Not Exist

Personally, I think No matching distribution found is the most misleading pip error message. The package usually DOES exist; pip is just rejecting every wheel it sees because of platform tags, Python version constraints, or markers you cannot see. I learned to run pip debug --verbose and pip index versions before anything else when this fires. 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

How pip Decides Nothing Matches

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.

Quick Reference Before You Dive In

If you arrived here from Google with a fresh No matching distribution found, the five facts that resolve roughly 90 percent of cases:

1. pip index versions PACKAGE confirms whether the package exists. If it lists versions, the package is there and pip is filtering for some reason. If it errors too, you have a typo or the wrong index. The pip user guide and PEP 425 wheel tag spec are the canonical sources.
2. pip debug --verbose prints the platform tags YOUR interpreter accepts. Compare with what PyPI publishes for the package. Mismatch = silent filter.
3. Update pip first. A pip from 2021 cannot see manylinux_2_28 wheels published in 2024 and falls back silently to “no matching distribution.”
4. The pip name often differs from the import name. pip install opencv-python (not cv2), pip install scikit-learn (not sklearn), pip install Pillow (not PIL).
5. In Alpine Docker, you need glibc-based images or build tools. Alpine uses musl libc; manylinux wheels do not load. Switch to python:3.12-slim or apk add gcc musl-dev python3-dev.

The rest of this article walks through each cause in detail, plus the failure modes most other guides skip.

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 is almost always changing the interpreter, the base image, or the wheel build constraints to produce tags that match what is on PyPI.

When to Use Which Fix

The next sections cover the fixes in detail. The table below maps your situation to the recommended fix.

If multiple rows apply, pick the topmost one.

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.

A specific trap I see in code reviews more often than I would like: assuming the pip name matches the import name. import sklearn works after pip install scikit-learn; import cv2 needs pip install opencv-python; import yaml needs pip install PyYAML. If a brand-new dev types the import name and gets “no matching distribution,” I check the import / pip name mismatch table before suggesting anything more elaborate.

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 do not provide ARM64 Windows wheels yet
• Alpine Linux: uses musl libc instead of glibc, so manylinux wheels do not 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/somepackage.git@v1.5.2

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 do not handle pyproject.toml-based builds.
• Packages with metadata 2.1+: older pip cannot 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

An habit I have built when joining a new project or onboarding a junior engineer: python -m pip install --upgrade pip is always the first command I run before debugging any pip issue. Older pip versions silently misread newer wheel metadata, so the “no matching distribution” error often vanishes with one upgrade and no other change. The two-minute cost is trivial compared to the hours of false-trail debugging it can prevent.

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.

Stranger Causes I Have Tracked Down

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; 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.

What Other Tutorials Get Wrong About This Error

Most pip tutorials list the same fixes but frame them in ways that produce subtle bugs.

They take “not found” literally. “No matching distribution” almost never means the package does not exist; it means pip filtered every wheel it saw. Tutorials that send readers searching for an alternative package send them down the wrong trail.

They omit pip debug --verbose. This single command shows which platform tags your interpreter accepts. Without it, debugging wheel-tag mismatches is guesswork. Articles that focus on --verbose for install miss that pip debug is the right tool for “why is this wheel rejected” questions.

They miss the Alpine musl distinction. python:3.12-alpine is widely promoted as a small base image, but it cannot install most ML / scientific packages because they ship only manylinux (glibc) wheels. Articles that recommend Alpine for size without warning about wheel compatibility leave readers stuck.

They miss PEP 508 environment markers. A requirement with ; python_version<"3.13" is silently skipped on 3.13, breaking dependents that needed it. Tutorials that focus only on version pins miss this gating mechanism.

They miss yanked versions. pip index versions only shows non-yanked releases by default. Articles that suggest checking “Does the version exist on PyPI?” miss that the version may exist but be yanked, which produces the same error.

They confuse No matching distribution with Could not build wheels. Both look similar but have different causes. The former means pip could not find any installable distribution. The latter means pip found a source distribution and tried to build it but the build failed. The fixes differ.

Frequently Asked Questions

How do I know if the package actually exists?

pip index versions PACKAGE_NAME. If it lists versions, the package exists and pip is filtering. If it errors too, you have a typo, the wrong index, or the package was never published. For PyPI specifically, visiting https://pypi.org/project/PACKAGE_NAME/ in a browser is the definitive check.

What is the difference between --index-url and --extra-index-url?

--index-url REPLACES the default PyPI index. --extra-index-url ADDS another index that pip searches alongside PyPI. Use --extra-index-url when you want packages from both your private index and PyPI; use --index-url only when you want to bypass PyPI entirely (e.g., air-gapped CI).

Why does Alpine Linux fail to install many packages?

Alpine uses musl libc, not glibc. Most pip wheels are tagged manylinux_*_x86_64 which require glibc. The wheels exist but cannot run on Alpine. Either switch to python:3.12-slim (Debian-based, glibc) or install build tools with apk add gcc musl-dev python3-dev and let pip build from source.

What does pip debug --verbose show me?

The list of platform tags your interpreter accepts (e.g., cp312-cp312-manylinux_2_28_x86_64). PyPI publishes wheels with their own tags; pip only installs wheels whose tags intersect with the accepted set. Tag mismatch is the silent cause of most “no matching distribution” errors.

Should I use --pre regularly?

No. --pre enables pre-release versions that may be unstable. Use it for testing upcoming releases or when a package has only ever shipped pre-releases. For production, pin specific stable versions and avoid --pre.

Why does my CI fail with No matching distribution but local works?

Three common reasons. First, your CI is on a different Python version (python3 may resolve differently). Second, your CI uses a different base image (Alpine vs slim). Third, your CI has a stale pip cache or pip version. Reproduce locally with the exact CI image and pip version to isolate which.

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