ERROR: Package '<pkg>' requires a different Python ... (Requires-Python mismatch)

Q: What does pip:REQUIRES_PYTHON_MISMATCH mean?

The package (or one of its dependencies) declares a `Requires-Python` range that excludes the Python interpreter you're using.

Q: How can I manually validate pip:REQUIRES_PYTHON_MISMATCH?

Check your interpreter version: `python -V`. Run `python -m pip install -v ` and read the `Requires-Python` messages in verbose output. If you're in a notebook, ensure the kernel Python matches the environment where you're running pip.

What This Error Means

The package (or one of its dependencies) declares a Requires-Python range that excludes the Python interpreter you're using.

How to Fix It

Use a compatible Python version for the package and create a new venv with it.

If you pinned a version, try a newer/older package version that supports your Python.

Make sure you're using the right interpreter:run python -m pip ... from the same python you want.

If this is in CI, ensure the runner's Python version matches your declared support range.

Why It Happens

You're using a Python version that is too new (no wheels released yet) or too old for the package.

Your constraints/pins force a version that doesn't support your interpreter.

You're installing with a different Python than you think (multiple Python installs, wrong venv).

How to Verify

Re-run python -m pip install <package> under the compatible Python and confirm pip finds a candidate.

Run python -c 'import <module>' to confirm the installed package imports.

Manual interpreter selection checks

Check your interpreter version:python -V

Run python -m pip install -v <package> and read the Requires-Python messages in verbose output.

If you're in a notebook, ensure the kernel Python matches the environment where you're running pip.

Examples

ERROR: Ignored the following versions that require a different python version: 2.2.0 Requires-Python >=3.8,<3.11
ERROR: Package 'uv-test' requires a different Python: 3.13.2 not in '<3.13,>=3.10'
ERROR: Package 'psychopy' requires a different Python: 3.12.5 not in '<3.11,>=3.8'

How pip uses Requires-Python

Packages can declare the Python versions they support via Requires-Python metadata.

pip reads that metadata and ignores releases that don't match your interpreter version, even if the version number matches your pin.

This commonly happens when using a newer Python than the package supports (or an older Python than required).

Prevention Tips

Pin a project Python version (and enforce it in tooling) to avoid accidental upgrades to unsupported versions.

Prefer lock/constraints files generated for a specific Python version.

Monitor upstream package support for new Python releases before upgrading.

Where This Can Be Triggered

github.com/pypa/pip/blob/25.3/src/pip/_internal/resolution/resolvelib/factory.py

pip raises UnsupportedPythonVersion with "Package '...' requires a different Python ..." when Requires-Python excludes the current interpreter. - GitHub

if len(causes) == 1:
    specifier = str(causes[0].requirement.specifier)
    message = (
        f"Package {causes[0].parent.name!r} requires a different "
        f"Python: {version} not in {specifier!r}"
    )
    return UnsupportedPythonVersion(message)

github.com/pypa/pip/blob/25.3/src/pip/_internal/resolution/resolvelib/factory.py

pip also logs the filtered candidates with "Ignored the following versions that require a different python version ...". - GitHub

if skipped_by_requires_python:
    logger.critical(
        "Ignored the following versions that require a different python "
        "version: %s",
        "; ".join(skipped_by_requires_python) or "none",
    )