sqlalchemy/alembic · error · RuntimeError

Script supports at least python {".".join(str(x) for x in lo

Error message

Script supports at least python {".".join(str(x) for x in lower_python)} but less than {".".join(str(x) for x in upper_python)} right now.

What it means

Raised as RuntimeError by generate_pyi_for_proxy in tools/write_pyi.py when the running Python interpreter version is outside the supported window [lower_python, upper_python) defined by PYTHON_VERSIONS = (3,14), (3,16) at write_pyi.py:37. This is a build/dev tooling guard — write_pyi.py generates .pyi stub files for Alembic's proxy classes and is only valid on the Python versions those stubs target. Running it on an incompatible interpreter would produce incorrect type stubs.

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 5551b5d35f)

Solutions

1. Install and use Python 3.14 (or whichever version is in the PYTHON_VERSIONS range) to run write_pyi.py.
2. Use pyenv or a version manager: pyenv install 3.14 && pyenv shell 3.14.
3. If you're a maintainer updating the supported range, update PYTHON_VERSIONS at write_pyi.py:37 to match.
4. If you don't need to regenerate stubs, skip this step — it's not part of normal Alembic usage.

Example fix

# before
python3.12 tools/write_pyi.py  # RuntimeError: supports 3.14 to <3.16

# after
pyenv install 3.14.0
pyenv shell 3.14.0
python tools/write_pyi.py

import sys

def is_supported_python_for_pyi(lower=(3,14), upper=(3,16)):
    v = sys.version_info
    return v >= lower and v < upper

import sys

def can_run_write_pyi() -> bool:
    """Type guard: True if current Python can run write_pyi.py."""
    return (3, 14) <= sys.version_info < (3, 16)

When it happens

Trigger: Running tools/write_pyi.py (e.g. via 'python tools/write_pyi.py' or a make/tox target) on a Python version less than 3.14 or >= 3.16. The check at write_pyi.py:69 compares sys.version_info against the PYTHON_VERSIONS tuple. This only affects developers contributing to Alembic who regenerate stub files, not end users.

Common situations: Contributing to Alembic and running the stub generation step with the wrong Python version. Local dev environment using system Python 3.12 or 3.13 when stubs require 3.14. CI configured with a Python version outside the supported range. After a Python version bump where PYTHON_VERSIONS wasn't updated.

Related errors

• Can't drop table in batch mode
• Constraint must have a name
• No such constraint: '%s'
• No such index: '%s'
• TODO

AI-assisted analysis of sqlalchemy/alembic@5551b5d35f (2026-08-11). Data as JSON: /api/errors/5c7f1bcf5ae57f67. Report an issue: GitHub.