pypa/pip · error · DistributionNotFound

No matching distribution found for {query}

Error message

No matching distribution found for {query}

What it means

Raised by IndexCommand.get_available_package_versions when finder.find_all_candidates(query) returns no versions (after optional prerelease filtering). This is a DistributionNotFound (a DiagnosticPipError), meaning pip contacted the index(es) but found zero installable candidates for the given name. Note this is the 'pip index versions' path, distinct from install-time DistributionNotFound which carries richer diagnostics.

Source

Thrown at src/pip/_internal/commands/index.py:149

            finder = self._build_package_finder(
                options=options,
                session=session,
                target_python=target_python,
                ignore_requires_python=options.ignore_requires_python,
            )

            versions: Iterable[Version] = (
                candidate.version for candidate in finder.find_all_candidates(query)
            )

            if self.should_exclude_prerelease(options, canonicalize_name(query)):
                versions = (
                    version for version in versions if not version.is_prerelease
                )
            versions = set(versions)

            if not versions:
                raise DistributionNotFound(
                    f"No matching distribution found for {query}"
                )

            formatted_versions = [str(ver) for ver in sorted(versions, reverse=True)]
            latest = formatted_versions[0]

        dist = get_installed_distribution(query)

        if options.json:
            structured_output = {
                "name": query,
                "versions": formatted_versions,
                "latest": latest,
            }

            if dist is not None:
                structured_output["installed_version"] = str(dist.version)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Verify the package name spelling against the index (e.g. on PyPI).
2. Ensure the correct --index-url / --extra-index-url is configured.
3. If only pre-releases exist, allow them: pip index versions --pre <name>.
4. Check --python-version / --platform / --abi filters are not excluding all wheels.
5. Confirm network/proxy reach the index: curl -I <index-url>/simple/<name>/.

Example fix

// before
pip index versions nonexistntpkg
// after
pip index versions numpy

# Pre-check the package exists on the index before 'pip index versions'
import urllib.request, json
url = index_url.rstrip("/") + f"/simple/{name}/"
try:
    with urllib.request.urlopen(url, timeout=10) as r:
        if r.status != 200:
            raise SystemExit(f"package {name!r} not reachable on {index_url}")
except Exception as e:
    raise SystemExit(f"cannot reach {url}: {e}")

try:
    run_pip(["index", "versions", name])
except DistributionNotFound:
    # fall back: retry with --pre, or surface a friendly message
    log.warning("no versions for %s on %s", name, index_url)

When it happens

Trigger: Running 'pip index versions <name>' where <name> does not exist on any configured index, or where all candidates are pre-releases and pre-releases are excluded by selection prefs.

Common situations: Typo in package name; package available on a private index not configured; package yanked/removed; --pre not set and only pre-releases exist; network/proxy returning an empty simple-API page; Python version filter excluding all wheels.

Related errors

• You need to specify exactly one argument
• XMLRPC request failed [code: {fault.faultCode}] {fault.fault
• No matching distribution found for {req}
• Error reading pylock file {pylock_path_or_url!r}: {exc}
• Unexpected HTTP request on what should be a secure connectio

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/d42b3b6b73ee5894.json. Report an issue: GitHub.