{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/index/package_finder.py#L1039-L1075","documentation":"DistributionNotFound raised at the end of find_best_candidate when no installable candidate was found AND nothing satisfying is already installed. The classic 'No matching distribution found for X' message; it logs the available versions (or 'none') before raising.","triggerScenarios":"Reached when installed_version is None and best_candidate is None after filtering all candidates by platform tags, requires-python, format control, prerelease policy, and hashes. Typo in package name, no compatible wheel/sdist on the index, or all versions excluded by version specifiers.","commonSituations":"Misspelled package name; requiring a version specifier that no release satisfies (e.g. '==1.2.4' that doesn't exist); Python version too new/old for every release (requires-python excludes all); index unreachable or empty; --only-binary with no wheel available; offline install with no local index.","solutions":["Verify the package name spelling and that it exists on the configured index (pip index versions <name> or check pypi.org).","Loosen the version specifier (drop ==, widen >=) so an existing release can match.","Check 'from versions:' in the log - if 'none', the index returned nothing (network/index URL issue or fully-incompatible requires-python).","Allow sdists by removing --only-binary, or allow prereleases with --pre if only pre-releases exist."],"exampleFix":"# before\npip install 'somepkg==1.2.4'   # version does not exist\n\n# after\npip index versions somepkg        # see what exists\npip install 'somepkg>=1.2,<2'      # pick an existing release","handlingStrategy":"try-catch","validationCode":"import subprocess, json, urllib.request\n# 1) check package exists\ntry:\n    json.load(urllib.request.urlopen(f'https://pypi.org/pypi/{name}/json'))\nexcept urllib.error.HTTPError:\n    print('package not found on index')\n# 2) check specifier has any match\nfrom packaging.requirements import Requirement\nreq = Requirement(spec)\nreleases = [Version(v) for v in data['releases']]\nif not any(req.specifier.contains(v, prereleases=True) for v in releases):\n    print('no version satisfies', spec)","typeGuard":"def requirement_satisfiable(name: str, spec: str) -> bool:\n    import urllib.request, json\n    from packaging.requirements import Requirement\n    from packaging.version import Version\n    d = json.load(urllib.request.urlopen(f'https://pypi.org/pypi/{name}/json'))\n    req = Requirement(f'{name}{spec}')\n    return any(req.specifier.contains(Version(v), prereleases=True)\n               for v in d['releases'])","tryCatchPattern":"from pip._internal.exceptions import DistributionNotFound\ntry:\n    pip.main(['install', req])\nexcept DistributionNotFound as e:\n    # log; suggest checking name/version/Python compat\n    ...","preventionTips":["Verify package names with 'pip index versions'.","Loosen version specifiers and avoid nonexistent exact pins.","Confirm Python version compatibility (requires-python).","Allow sdist/prereleases when wheels/prereleases are the only option."],"tags":["resolution","distribution-not-found","index","specifier"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}