ERROR: No matching distribution found (and "Could not find a version that satisfies the requirement")

Q: How can I manually validate pip:NO_MATCHING_DISTRIBUTION?

Check Python version and platform: `python -c 'import sys, platform; print(sys.version); print(platform.platform())'`. Check whether pip is using a custom index/mirror: `python -m pip config list`. Re-run the failing install with verbose logs: `python -m pip install -v == `.

What This Error Means

pip could not find any installable release that matches your requirement and your environment (Python version, OS/architecture, and index configuration).

How to Fix It

Confirm you're installing into the intended interpreter and environment:python -m pip --version

If you pinned a version, try relaxing or changing the pin to a version that exists and supports your Python.

If you are on a very new Python, consider using a supported Python version for the package (create a new venv with that Python).

If using a private index, confirm it contains the project/version or configure --index-url / --extra-index-url appropriately.

If the package requires a special index (some ML packages do), follow that package's install instructions for the correct index and wheel selection.

Why It Happens

The pinned version doesn't exist on the index you're using (yanked/removed or never published there).

Your Python version is unsupported for that package release (Requires-Python mismatch).

No wheel exists for your OS/architecture/Python ABI, and building from source is unavailable or blocked.

You're using the wrong index URL (private mirror missing the project, or index misconfigured).

How to Verify

Re-run the install and confirm pip selects a candidate and proceeds to download/build.

Run python -c 'import <module>' (or python -m pip show <package>) to confirm installation succeeded.

Manual compatibility checks

Check Python version and platform:python -c 'import sys, platform; print(sys.version); print(platform.platform())'

Check whether pip is using a custom index/mirror:python -m pip config list

Re-run the failing install with verbose logs:python -m pip install -v <package>==<version>

Examples

ERROR: Could not find a version that satisfies the requirement awswrangler==1.0.0
ERROR: No matching distribution found for awswrangler==1.0.0
ERROR: Could not find a version that satisfies the requirement tensorflow~=2.4.1
ERROR: No matching distribution found for tensorflow~=2.4.1

How pip selects compatible distributions

pip selects packages from an index (like PyPI or a private mirror) and filters candidates by your constraints (version specifiers) and by environment compatibility (Requires-Python, wheel tags for OS/arch/ABI).

If every candidate is filtered out (or the index returns none), pip reports that no matching distribution/version satisfies the requirement.

Prevention Tips

Avoid overly strict pins unless you maintain them (especially for platform-specific packages).

Standardize Python versions across dev/CI to reduce compatibility surprises.

Use a repository manager/mirror and ensure it proxies the required projects and versions.

Where This Can Be Triggered

github.com/pypa/pip/blob/25.3/src/pip/_internal/index/package_finder.py

pip logs "Could not find a version that satisfies ..." and raises DistributionNotFound ("No matching distribution found for ...") when no candidate matches your environment/constraints. - GitHub

if installed_version is None and best_candidate is None:
    logger.critical(
        "Could not find a version that satisfies the requirement %s "
        "(from versions: %s)",
        req,
        _format_versions(best_candidate_result.all_candidates),
    )

    raise DistributionNotFound(f"No matching distribution found for {req}")