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

Q: How do I prevent pip:NO_MATCHING_DISTRIBUTION in CI?

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.

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 Does Not Match This Runtime or Platform

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

Check runtime, platform, and index source

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

Use a compatible runtime, platform, or published build

Start by checking the compatibility boundary itself: runtime version, platform, architecture, and whether a matching build was ever published for that combination.

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 This Runtime or Platform Does Not Match

Usually this comes down to 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, or you're using the wrong index URL (private mirror missing the project, or index misconfigured).

Prove the Runtime and Published Build Now Line Up

Re-run the install and confirm pip selects a candidate and proceeds to download/build, and run python -c 'import <module>' (or python -m pip show <package>) to confirm installation succeeded.

Typical Output

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 looks up package versions

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.

Avoid Version and Source Drift

To prevent this, avoid overly strict pins unless you maintain them (especially for platform-specific packages), standardize Python versions across dev/CI to reduce compatibility surprises, and use a repository manager/mirror and ensure it proxies the required projects and versions.

Docs and source code

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}")