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

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

1. Confirm you're installing into the intended interpreter and environment: python -m pip --version.
2. If you pinned a version, try relaxing or changing the pin to a version that exists and supports your Python.
3. If you are on a very new Python, consider using a supported Python version for the package (create a new venv with that Python).
4. If using a private index, confirm it contains the project/version or configure --index-url / --extra-index-url appropriately.
5. 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

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

Manual compatibility checks

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

Common CLI 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 selects compatible distributions

1. 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).
2. 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

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