Diagnosing pip "No matching distribution found" Errors from PyPI

The failure you are seeing

When pip install stops with ERROR: Could not find a version that satisfies the requirement <name> (from versions: ...) or ERROR: No matching distribution found for <name>, the resolver has examined every distribution on the configured index and rejected all of them. The useful takeaway is that the rejection is almost always local: a name typo, an interpreter version mismatch, a platform tag mismatch, or an index configuration problem. It is rarely a PyPI outage.

Recognizable condition

pip aborts before downloading or installing anything. The error text includes either a from versions: list, which shows candidates that were considered but rejected, or a bare No matching distribution found line. Both mean the same thing: no distribution on the index satisfied the combined constraints of package name, Requires-Python, platform compatibility tags, and any environment markers in your requirement.

Cause and diagnostic table

Clue in the error	Likely cause	First thing to inspect
Empty or missing from versions: list	Mistyped name, or a private package that is not on the public index	Exact project name on PyPI; configured index URL
Releases are listed, but none are accepted	Every release's Requires-Python excludes your interpreter	python -V against the project's Requires-Python
Releases exist, but no wheel tag matches	No compatible wheel or sdist for your platform/ABI	Release file list; wheel platform tags
A known version is absent from candidates	The release is yanked and pip skips it unless pinned exactly	PyPI release history for yanked status
pip fails on newer metadata formats	Stale pip or setuptools cannot parse current core metadata	pip --version
pip cannot reach the index	index-url/extra-index-url misconfiguration or missing credentials	pip config list and PIP_INDEX_URL
Package is excluded by a marker or extra	Environment markers or extras in the requirement filter it out	The full requirement string, including [...] and ; ...

Ordered checks

Run these in order. Each check is designed to either eliminate a cause or produce a concrete finding you can act on.

1. Confirm the exact project name and index

Verify the project is spelled exactly as it appears on PyPI and that it is public. If you expect a private package, confirm the index URL and credentials. A missing credential on a private index produces the same error as a nonexistent package.

Where: Terminal or shell.
Permissions: Network access; read access to pip config.
Check: Compare the requirement name against the canonical PyPI project name. If using a private index, confirm the URL and token are supplied via PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, or a pip config file.
Risk: None.

2. Compare Requires-Python with your interpreter

Many projects declare a Requires-Python range. If your interpreter falls outside that range, pip will not consider any release.

Where: Terminal.
Command: python -V (or python3 -V).
Check: Compare the output against the project's Requires-Python metadata on PyPI. If the project requires, for example, Python 3.9+ and you are running 3.8, no release will match.
Risk: None.

3. Test whether any distribution file can be resolved

This check separates a metadata problem from a file-availability problem without installing anything. A wheel (.whl) is a pre-built distribution; an sdist (.tar.gz) is a source archive that may require compilation.

Where: Terminal, in any working directory with write access to a temp directory.
Command: python -m pip download --no-deps --dest /tmp <name>==<version>
Placeholders: Replace <name> with the project name and <version> with a specific release.
Expected check: If pip downloads a .whl or .tar.gz file, a compatible distribution exists. If it fails with the same resolver error, no file on the index matches your environment.
Risk: Consumes disk space in the destination directory. The download itself does not execute package code.

4. Check your pip version

Older pip versions may ignore Requires-Python, fail to parse newer core metadata, or lack support for recent PEP standards.

Where: Terminal.
Command: python -m pip --version
Check: Compare against the latest stable pip release. If the version is significantly old, upgrade before retrying.
Fix: python -m pip install -U pip using the same interpreter you use for installation. If you need to revert afterward, install a specific version with python -m pip install pip==<version>.
Risk: Upgrading pip changes the installer itself. Use the explicit python -m pip form to avoid upgrading a different interpreter's pip.

5. Inspect effective index settings

pip may be pointed at a mirror, a private index, or a stale configuration that shadows PyPI.

Where: Terminal.
Command: python -m pip config list
Check: Look for index-url, extra-index-url, and any find-links entries. Also check the environment variables PIP_INDEX_URL and PIP_EXTRA_INDEX_URL. If a private index is listed first and the package is not there, pip may never query PyPI.
Risk: Changing index URLs can redirect package resolution to untrusted sources. Only modify them if you control the target.

6. Determine whether the target version is yanked

A yanked release is hidden from normal resolution but can still be installed if pinned exactly.

Where: Terminal (to inspect) and PyPI project page (to confirm).
Check: On the project's PyPI page, look at the release history for the version you want. If it is marked yanked, pip will skip it unless you pin the exact version.
Risk: Pinning a yanked version may succeed but is usually not a supported long-term fix, because yanked releases are often withdrawn for security or correctness reasons.

7. Evaluate environment markers and extras

A requirement such as package[extra]; python_version < "3.9" may be excluded by your current interpreter or by the absence of the extra.

Where: Terminal.
Check: Read the full requirement string. If it contains a semicolon, the text after it is an environment marker. If it contains square brackets, those are extras. Confirm the marker evaluates true for your interpreter and that you actually need the extra.
Risk: None.

Fixes tied to findings

• Name typo or private package: Correct the spelling, or configure the private index URL and credentials.
• Requires-Python mismatch: Choose a release whose Requires-Python covers your interpreter, or switch to a compatible interpreter.
• No compatible wheel: Install from the sdist if one exists, ensuring you have the build toolchain and build dependencies. Building from an sdist executes arbitrary setup code; only do this for trusted packages in an isolated environment.
• Stale pip: Upgrade pip with python -m pip install -U pip and retry.
• Index misconfiguration: Set the correct index-url or supply credentials for the private index.
• Yanked release: Pin a non-yanked version explicitly. Pinning a yanked version is possible but generally not recommended.
• Marker or extra exclusion: Adjust the requirement string so the marker matches your environment, or install the needed extra.

Do not use --python-version or --platform to force an install into your running environment. Those flags are for cross-environment inspection only and can produce an incompatible environment.

Escalation criteria

Escalate only after the local checks above are exhausted:

• PyPI operators: Escalate when the project is public, its metadata and file list look correct, and multiple recent pip versions still fail. Include the full python -m pip install -v <name> log and the project's JSON API response.
• Project maintainer: File an issue when a specific release is unbuildable from its sdist or lacks wheels for a supported platform.
• pip issue tracker: File an issue when verbose output shows a resolver crash or a metadata-parsing bug that is not explained by the project's published metadata.

Verification and limitations

To verify a fix, reproduce the original failure deterministically in a clean virtual environment, apply the fix, and confirm the install succeeds:

python -m venv /tmp/pip-check
source /tmp/pip-check/bin/activate  # Linux/macOS
# /tmp/pip-check/Scripts/activate  # Windows
python -m pip install -v <name>

Compare pip's view of the project with PyPI's JSON API (https://pypi.org/pypi/<name>/json). If pip reports no candidates but the JSON API lists compatible files with a matching requires_python, the fault is local to pip or your index configuration.

Limitations: pip's resolver, PEP 517/518 in-tree builds, Requires-Python enforcement, and PEP 658 metadata retrieval have changed across pip and Python releases. Older pip may behave differently from current versions, and very new Python releases often lack wheels until maintainers publish them. Treat exact error text and defaults as version-dependent, and verify current pip and PyPI behavior before relying on specific strings.