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

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

1. Use a compatible Python version for the package and create a new venv with it.
2. If you pinned a version, try a newer/older package version that supports your Python.
3. Make sure you're using the right interpreter: run python -m pip ... from the same python you want.
4. 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

1. Re-run python -m pip install <package> under the compatible Python and confirm pip finds a candidate.
2. Run python -c 'import <module>' to confirm the installed package imports.

Manual interpreter selection checks

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

Common CLI Output

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

1. Packages can declare the Python versions they support via Requires-Python metadata.
2. pip reads that metadata and ignores releases that don't match your interpreter version, even if the version number matches your pin.
3. 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

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)

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",
    )