pypa/pip · error · UnsupportedPythonVersion

Package {dist.raw_name!r} requires a different Python: {vers

Error message

Package {dist.raw_name!r} requires a different Python: {version} not in {requires_python!r}

What it means

UnsupportedPythonVersion raised by the legacy resolver's _check_requires_python when the distribution's Requires-Python specifier excludes the currently running Python version and --ignore-requires-python is not set. pip reads Requires-Python from metadata, compares it to sys.version_info via check_requires_python, and aborts with both the current version and the offending specifier so the user can see the mismatch.

Source

Thrown at src/pip/_internal/resolution/legacy/resolver.py:105

        logger.warning(
            "Package %r has an invalid Requires-Python: %s", dist.raw_name, exc
        )
        return

    if is_compatible:
        return

    version = ".".join(map(str, version_info))
    if ignore_requires_python:
        logger.debug(
            "Ignoring failed Requires-Python check for package %r: %s not in %r",
            dist.raw_name,
            version,
            requires_python,
        )
        return

    raise UnsupportedPythonVersion(
        f"Package {dist.raw_name!r} requires a different Python: "
        f"{version} not in {requires_python!r}"
    )


class Resolver(BaseResolver):
    """Resolves which packages need to be installed/uninstalled to perform \
    the requested operation without breaking the requirements of any package.
    """

    _allowed_strategies = {"eager", "only-if-needed", "to-satisfy-only"}

    def __init__(
        self,
        preparer: RequirementPreparer,
        finder: PackageFinder,
        wheel_cache: WheelCache | None,
        make_install_req: InstallRequirementProvider,

View on GitHub (pinned to d7d0d0a394)

Solutions

Upgrade your interpreter to one satisfying the Requires-Python specifier shown in the error.
Pin an older version of the package that still supports your Python: 'pkg==<older>'.
If you accept the risk, bypass the check with '--ignore-requires-python' (not recommended for production).
Verify which Python pip is using: 'pip -V' and 'python --version'.

Example fix

# before — Python 3.8
pip install 'newpkg>=2.0'   # newpkg>=2.0 requires Python >=3.9

# after (option A: upgrade interpreter; option B: pin older)
pip install 'newpkg<2.0'

Defensive patterns

Strategy: validation

Validate before calling

import sys
from pip._vendor.packaging.specifiers import SpecifierSet
def python_satisfies(requires_python: str) -> bool:
    return SpecifierSet(requires_python).contains('.'.join(map(str, sys.version_info[:3])))

Type guard

def is_python_compatible(requires_python: str) -> bool:
    return python_satisfies(requires_python)

Try / catch

from pip._internal.exceptions import UnsupportedPythonVersion
try:
    run_pip(['install', 'pkg'])
except UnsupportedPythonVersion:
    run_pip(['install', '--ignore-requires-python', 'pkg'])  # or upgrade Python / pin older pkg

Prevention

Keep your interpreter within the supported range of your dependencies.
Check Requires-Python before adding a dependency: 'pip index versions pkg'.
Use '--ignore-requires-python' only as a last resort.

When it happens

Trigger: Installing a package whose metadata declares e.g. 'Requires-Python: >=3.9' while running Python 3.8 (or '<4' while on a 4.x). Triggered during dependency resolution when the legacy resolver evaluates a candidate distribution.

Common situations: Running an older Python than a package supports; new release that bumped its minimum Python; CI matrix using Python 3.8 for a dependency that now requires 3.9+; pyenv/conda env pointing at the wrong interpreter.

Related errors

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