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 do I prevent pip:REQUIRES_PYTHON_MISMATCH in CI?

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.

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.

Fix it fast

Most likely: The package metadata excludes the Python version you are using. pip is doing the right thing by ignoring releases whose Requires-Python range does not include your interpreter.

1. Confirm this is your error

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'

2. Check the cause

python -V
python -m pip --version
python -m pip install -v <package>
python -c 'import sys; print(sys.executable)'

3. Apply the safe fix

# Use a Python version that the package supports, then install in a fresh venv.
python<supported-version> -m venv .venv
. .venv/bin/activate
python -m pip install <package>

# Or choose a package version that supports your current Python.
python -m pip install "<package>==<compatible-version>"

4. Verify it works

python -V
python -m pip show <package>
python -c 'import <module>; print("ok")'

Don't use unsafe shortcuts

Do not force-install a release that declares it does not support your Python.
Do not assume the newest Python is supported by every package yet.
Do not debug indexes or mirrors until you confirm the Requires-Python range.

What Does Not Match This Runtime or Platform

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

Use a compatible runtime, platform, or published build

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 This Runtime or Platform Does Not Match

Usually this comes down to 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, or you're installing with a different Python than you think (multiple Python installs, wrong venv).

Prove the Runtime and Published Build Now Line Up

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

Check runtime, platform, and index source

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.

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).

Prevent It From Coming Back

To prevent this, 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, and monitor upstream package support for new Python releases before upgrading.

Docs and source code

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