{"record":{"id":"bae81a6befac1d67","repo":"pypa/pip","slug":"no-matching-distribution-found-for-req","errorCode":null,"errorMessage":"No matching distribution found for {req}","messagePattern":"No matching distribution found for (.+?)","errorType":"exception","errorClass":"DistributionNotFound","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/index/package_finder.py","lineNumber":1057,"sourceCode":"        if installed_version is None and best_candidate is None:\n            # Check if only final releases are allowed for this package\n            version_type = \"version\"\n            if self.release_control is not None:\n                allows_pre = self.release_control.allows_prereleases(\n                    canonicalize_name(name)\n                )\n                if allows_pre is False:\n                    version_type = \"final version\"\n\n            logger.critical(\n                \"Could not find a %s that satisfies the requirement %s \"\n                \"(from versions: %s)\",\n                version_type,\n                req,\n                _format_versions(best_candidate_result.all_candidates),\n            )\n\n            raise DistributionNotFound(f\"No matching distribution found for {req}\")\n\n        def _should_install_candidate(\n            candidate: InstallationCandidate | None,\n        ) -> TypeGuard[InstallationCandidate]:\n            if installed_version is None:\n                return True\n            if best_candidate is None:\n                return False\n            return best_candidate.version > installed_version\n\n        if not upgrade and installed_version is not None:\n            if _should_install_candidate(best_candidate):\n                logger.debug(\n                    \"Existing installed version (%s) satisfies requirement \"\n                    \"(most up-to-date version is %s)\",\n                    installed_version,\n                    best_candidate.version,\n                )","sourceCodeStart":1039,"sourceCodeEnd":1075,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/index/package_finder.py#L1039-L1075","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the package name and requested version exist on the configured index (check the index URL in a browser).","Loosen the version specifier or remove an upper bound that excludes all releases.","Add --pre if the only available releases are pre-releases.","Confirm network/proxy access to the index URL and that PYTHONPATH/index config points at a populated index."],"exampleFix":"// before\npip install 'django==99.0'\n// after\npip install 'django>=5.0,<6.0'","handlingStrategy":"validation","validationCode":"// Before installing, confirm the requirement is satisfiable on this index:\nfrom pip._internal.utils.compatibility_tags import get_supported\nfrom pip._vendor.packaging.requirements import Requirement\nreq = Requirement('mypkg>=1.0')\n# fetch the simple index JSON/HTML and check a version matching req.specifier exists\n# and that a wheel matches get_supported() platform tags or an sdist is allowed","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import DistributionNotFound\ntry:\n    best = finder.find_best_candidate(req)\nexcept DistributionNotFound:\n    # fall back: add --pre, loosen specifier, or switch index\n    ...","preventionTips":["Double-check package name spelling and version specifiers against the index.","Add --pre when only pre-releases exist for the requested version range.","In offline/air-gapped setups, ensure find-links/index actually contain the package."],"tags":["installation","resolution","distribution-not-found","index"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}