pypa/pip · error · UnsupportedPythonVersion

Script {script!r} requires a different Python: {target_pytho

Error message

Script {script!r} requires a different Python: {target_python.py_version} not in {script_requires_python!r}

What it means

Raised by RequirementCommand.get_requirements() in req_command.py:417 when a PEP 723 script's requires-python field is incompatible with the target Python version (derived from --python-version or the running interpreter). The check uses check_requires_python() against the script's declared Requires-Python specifier. This prevents installing dependencies that won't work with the interpreter being used.

Source

Thrown at src/pip/_internal/cli/req_command.py:417

            if len(options.requirements_from_scripts) > 1:
                raise CommandError("--requirements-from-script can only be given once")

            script = options.requirements_from_scripts[0]
            try:
                script_metadata = pep723_metadata(script)
            except PEP723Exception as exc:
                raise CommandError(exc.msg)

            script_requires_python = script_metadata.get("requires-python", "")

            if script_requires_python and not options.ignore_requires_python:
                target_python = make_target_python(options)

                if not check_requires_python(
                    requires_python=script_requires_python,
                    version_info=target_python.py_version_info,
                ):
                    raise UnsupportedPythonVersion(
                        f"Script {script!r} requires a different Python: "
                        f"{target_python.py_version} not in {script_requires_python!r}"
                    )

            for req in script_metadata.get("dependencies", []):
                req_to_add = install_req_from_req_string(
                    req,
                    isolated=options.isolated_mode,
                    user_supplied=True,
                )
                requirements.append(req_to_add)

        if options.require_hashes and options.no_require_hashes:
            raise CommandError(
                "--require-hashes and --no-require-hashes are mutually exclusive"
            )

        # If any requirement has hash options, enable hash checking for all

View on GitHub (pinned to d7d0d0a394)

Solutions

Upgrade to a Python version that satisfies the script's requires-python constraint.
Use `--python-version` to target the correct version if cross-installing.
Add `--ignore-requires-python` to bypass the check (at your own risk).
Update the script's requires-python field if the constraint is too strict.

Example fix

# before
# myscript.py has: requires-python = ">=3.12"
# running Python 3.10
pip install --requirements-from-script myscript.py

# after
# Option A: use the right Python
python3.12 -m pip install --requirements-from-script myscript.py
# Option B: bypass the check
pip install --ignore-requires-python --requirements-from-script myscript.py

Defensive patterns

Strategy: validation

Validate before calling

import sys, re
from pip._internal.utils.compat import tomllib
from pip._internal.utils.packaging import check_requires_python

def validate_script_python_compat(filepath, python_version=None):
    """Check if the running Python satisfies the script's requires-python."""
    from pip._internal.req.pep723 import pep723_metadata
    metadata = pep723_metadata(filepath)
    requires_python = metadata.get('requires-python', '')
    if not requires_python:
        return True
    version = python_version or sys.version_info[:2]
    return check_requires_python(requires_python=requires_python, version_info=version)

Try / catch

from pip._internal.exceptions import UnsupportedPythonVersion
try:
    # pip install --requirements-from-script script.py
except UnsupportedPythonVersion as e:
    # script requires newer/older Python; upgrade interpreter or add --ignore-requires-python

Prevention

Match your Python version to the script's requires-python before installing.
Use pyenv to manage multiple Python versions.
Keep requires-python constraints accurate in PEP 723 scripts.
Use --ignore-requires-python only when you understand the risks.

When it happens

Trigger: Calling `pip install --requirements-from-script myscript.py` where myscript.py has `requires-python = ">=3.11"` in its PEP 723 block, but the running Python (or --python-version) is 3.10 or earlier. The check at req_command.py:410-416 is skipped if --ignore-requires-python is set.

Common situations: Running a script designed for a newer Python on an older interpreter. CI images with mismatched Python versions. Development environment Python version doesn't match the script's requirements. Script was written for a different Python than the developer's local setup.

Related errors

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