pypa/pip · error · DistributionNotFound

No matching distribution found for

Error message

No matching distribution found for {query}

What it means

Raised by `pip index versions` when the package finder returns zero candidate versions for the query. get_available_package_versions at index.py:148 builds a set of candidate versions from finder.find_all_candidates(query); if the set is empty it raises DistributionNotFound. This can mean the package does not exist on any configured index, all candidates were yanked/excluded, or requires-python filtering removed everything.

Solutions

  1. Verify the package name on the index (e.g. pypi.org) — check for typos.
  2. Add the correct index: `--index-url` or `--extra-index-url` pointing at where the package lives.
  3. Try `--pre` if only pre-release versions exist and prereleases are excluded by default.
  4. Adjust `--python`/`--ignore-requires-python` if requires-python filtering removed all candidates.
  5. Confirm the package isn't fully yanked on the index.

Example fix

// before
pip index versions nonexistntpkg
// after
pip index versions numpy
# or add a private index
pip index versions privatepkg --extra-index-url https://my.repo/simple
Defensive patterns

Strategy: validation

Validate before calling

# Pre-check the package exists on the index before pip index versions
import subprocess, json

def package_has_versions(name, index_url=None):
    cmd = ["pip", "index", "versions", name, "--json"]
    if index_url:
        cmd += ["--extra-index-url", index_url]
    r = subprocess.run(cmd, capture_output=True, text=True)
    if r.returncode != 0:
        return False
    data = json.loads(r.stdout)
    return len(data.get("versions", [])) > 0

Try / catch

# Retry with alternate index on DistributionNotFound
import subprocess
try:
    subprocess.run(["pip", "index", "versions", name], check=True)
except subprocess.CalledProcessError:
    subprocess.run(["pip", "index", "versions", name, "--pre", "--ignore-requires-python"], check=True)

Prevention

When it happens

Trigger: Querying a non-existent package name, a package only available on an index not configured, a package whose every release is yanked, or a package with no version compatible with the target Python (--python / requires-python).

Common situations: Typo in the package name, private index not added via --index-url/--extra-index-url, yanked releases, or targeting a Python version the package never supported.

Related errors

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

Appendix: 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 f399c37189)