pypa/pip · error · DistributionNotFound

No matching distribution found for

Error message

No matching distribution found for {req}

What it means

The canonical DistributionNotFound error, raised in find_best_candidate (package_finder.py:1057) after collecting all candidates and finding none that satisfy the requirement. It means every source pip consulted (configured index URLs, find-links) yielded zero compatible candidates after applying version specifiers, platform tags, and python-requires filters.

Solutions

1. Verify the package name and requested version exist on the configured index (check the index URL in a browser).
2. Loosen the version specifier or remove an upper bound that excludes all releases.
3. Add --pre if the only available releases are pre-releases.
4. Confirm network/proxy access to the index URL and that PYTHONPATH/index config points at a populated index.

Example fix

// before
pip install 'django==99.0'
// after
pip install 'django>=5.0,<6.0'

// Before installing, confirm the requirement is satisfiable on this index:
from pip._internal.utils.compatibility_tags import get_supported
from pip._vendor.packaging.requirements import Requirement
req = Requirement('mypkg>=1.0')
# fetch the simple index JSON/HTML and check a version matching req.specifier exists
# and that a wheel matches get_supported() platform tags or an sdist is allowed

from pip._internal.exceptions import DistributionNotFound
try:
    best = finder.find_best_candidate(req)
except DistributionNotFound:
    # fall back: add --pre, loosen specifier, or switch index
    ...

When it happens

Trigger: find_best_candidate exhausts best_candidate_result with no applicable candidates, so it logs the available versions and raises DistributionNotFound. Common with a misspelled package name, an unavailable version specifier (e.g. >=99), a Python version for which no wheel/sdist exists, or all candidates being pre-releases while pre-releases are disallowed.

Common situations: Typosquatting/typo in package name; pinning a version that doesn't exist; using a Python version newer/older than any released wheel supports; corporate proxy blocking the index so the page appears empty; --no-binary forcing sdist when only wheels exist (or vice versa); pre-release-only releases with default pip pre-release exclusion.

Related errors

• Could not install locked package
• Index does not provide upload-time metadata.
• Multiple locked links provided for
• Cannot determine archive format of
• Cannot set --home and --prefix together

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/bae81a6befac1d67. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/index/package_finder.py:1057

        if installed_version is None and best_candidate is None:
            # Check if only final releases are allowed for this package
            version_type = "version"
            if self.release_control is not None:
                allows_pre = self.release_control.allows_prereleases(
                    canonicalize_name(name)
                )
                if allows_pre is False:
                    version_type = "final version"

            logger.critical(
                "Could not find a %s that satisfies the requirement %s "
                "(from versions: %s)",
                version_type,
                req,
                _format_versions(best_candidate_result.all_candidates),
            )

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

        def _should_install_candidate(
            candidate: InstallationCandidate | None,
        ) -> TypeGuard[InstallationCandidate]:
            if installed_version is None:
                return True
            if best_candidate is None:
                return False
            return best_candidate.version > installed_version

        if not upgrade and installed_version is not None:
            if _should_install_candidate(best_candidate):
                logger.debug(
                    "Existing installed version (%s) satisfies requirement "
                    "(most up-to-date version is %s)",
                    installed_version,
                    best_candidate.version,
                )

View on GitHub (pinned to f399c37189)