sqlalchemy/alembic · error · RuntimeError

Script supports at least python {lower_python} but less than

Error message

Script supports at least python {lower_python} but less than {upper_python} right now.

What it means

Raised as RuntimeError in generate_pyi_for_proxy (tools/write_pyi.py:70) when the Python interpreter running the .pyi stub-generation tool is outside the supported window defined by PYTHON_VERSIONS ((3,14), (3,16)). The generator inspects type annotations and proxy internals that are version-specific, so running it on an unsupported interpreter would produce incorrect stubs; it refuses instead.

Source

Thrown at tools/write_pyi.py:70

    "sqlalchemy.sql.schema.",
    "sqlalchemy.sql.selectable.",
    "sqlalchemy.sql.type_api.",
    "typing.",
]
ADDITIONAL_ENV = {
    "MigrationContext": MigrationContext,
    "AutogenContext": AutogenContext,
    "DefaultImpl": DefaultImpl,
    "MigrationInfo": MigrationInfo,
}


def generate_pyi_for_proxy(
    file_info: FileInfo, destination_path: Path, ignore_output: bool
):
    lower_python, upper_python = PYTHON_VERSIONS
    if sys.version_info < lower_python or sys.version_info >= upper_python:
        raise RuntimeError(
            f"Script supports at least python "
            f"{".".join(str(x) for x in lower_python)} "
            f"but less than {".".join(str(x) for x in upper_python)} "
            "right now."
        )

    progname = Path(sys.argv[0]).as_posix()
    # When using an absolute path on windows, this will generate the correct
    # relative path that shall be written to the top comment of the pyi file.
    if Path(progname).is_absolute():
        progname = Path(progname).relative_to(Path().cwd()).as_posix()

    file_info.read_file()

    cls = file_info.target
    with open(destination_path, "w") as buf:
        file_info.write_before(buf, progname)

View on GitHub (pinned to 44fb345033)

Solutions

1. Run the script under a supported Python version (install pyenv/uv python 3.14 or 3.15 within the window).
2. If you maintain a fork, update PYTHON_VERSIONS to match your generator interpreter.
3. Skip stub regeneration if you are not modifying proxied APIs — the checked-in .pyi files are sufficient.
4. Use `python3.14 tools/write_pyi.py` (or the in-range version) explicitly rather than the default `python`.

Example fix

# before: running on system python 3.12
python tools/write_pyi.py  # RuntimeError

# after: use a supported version
pyenv install 3.15
python3.15 tools/write_pyi.py

import sys
PYTHON_VERSIONS = (3, 14), (3, 16)  # mirror tools/write_pyi.py

def python_in_range() -> bool:
    lo, hi = PYTHON_VERSIONS
    return lo <= sys.version_info[:2] < hi

if not python_in_range():
    raise SystemExit('Use Python >=3.14 and <3.16 to run write_pyi.py')

try:
    generate_pyi_for_proxy(file_info, dest, ignore_output=False)
except RuntimeError as e:
    if 'supports at least python' in str(e):
        print('Install/run a supported Python (3.14 or 3.15) before regenerating stubs.')
    raise

When it happens

Trigger: Invoking tools/write_pyi.py (the Alembic maintainer stub-generation script) under Python 3.13 or earlier, or 3.16+, or any version outside [lower_python, upper_python). It is a development/maintainer tool, not part of normal Alembic usage.

Common situations: A contributor running the stub generator locally on their system Python which is older than the required dev version; CI using a different Python than the matrix expects; the PYTHON_VERSIONS constant was bumped in a newer Alembic but the local checkout is behind/ahead.

Related errors

• Can't drop table in batch mode
• Constraint must have a name
• No such constraint: '%s'
• No such index: '%s'
• constraint cannot be produced; original constraint is not pr

AI-assisted analysis of sqlalchemy/alembic@44fb345033 (2026-08-04). Data as JSON: /data/errors/b356bdafc46446dc.json. Report an issue: GitHub.