---
id: sqlalchemy2-stubs
version: "0.0.2a38"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# sqlalchemy2-stubs — Typing Stubs for SQLAlchemy 1.4

License: permissive · Maintenance: dormant · Downloads: 2.6M/mo

## What it is and what it does

sqlalchemy2-stubs provides typing stub files (PEP-484) for SQLAlchemy 1.4, allowing static type checkers to understand SQLAlchemy's ORM API and catch type errors at development time. The stubs are designed to work alongside a mypy extension plugin, which adds special handling for ORM mapped classes.

This package is explicitly a bridge for SQLAlchemy 1.4 users and is not compatible with SQLAlchemy 2.0, which ships with inline type annotations. The project is in alpha status and dormant—released concurrently with SQLAlchemy 1.4 and no longer actively maintained. Users upgrading to SQLAlchemy 2.0 must manually uninstall these stubs to avoid conflicts with the library's native typing.

Use it for:

- Enable type checking on SQLAlchemy 1.4 ORM code to catch column access and relationship errors before runtime.
- Provide IDE autocomplete and type hints for SQLAlchemy models and query objects in editors supporting PEP-484 stubs.
- Validate type consistency in legacy SQLAlchemy 1.4 projects during migration planning or refactoring.
- Support gradual typing adoption in existing SQLAlchemy 1.4 codebases without rewriting the library itself.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides PEP-484 typing stubs for SQLAlchemy 1.4, enabling static type checking with mypy and other type checkers.

Yes, if you are actively maintaining SQLAlchemy 1.4 code and want static type checking. The low install friction and permissive MIT license make it straightforward to add. However, this is a legacy package: it is dormant, explicitly incompatible with SQLAlchemy 2.0, and must be manually uninstalled before upgrading. Do not install if you are on or planning to migrate to SQLAlchemy 2.0.

## Install

pip install sqlalchemy2-stubs
uv add sqlalchemy2-stubs
poetry add sqlalchemy2-stubs

## Installing sqlalchemy2-stubs

Before you install: Low install friction with a single lightweight dependency on typing-extensions. Maintenance is dormant—last commit was 2023-12-30 and no releases in 958 days—which is expected for a legacy typing stub package.

License in practice: MIT license permits permissive use, modification, and distribution with minimal restrictions, making it safe to adopt in most projects.

Quickstart:

pip install sqlalchemy2-stubs typing-extensions

from typing_extensions import TypedDict
# Use with SQLAlchemy 1.4 ORM code for type checking

Only compatible with SQLAlchemy 1.4; must be manually uninstalled before upgrading to SQLAlchemy 2.0, which includes inline typing and will conflict with these stubs.

Verify before relying:

- Whether the stubs cover the full SQLAlchemy 1.4 API surface or only a subset (description notes 'interim' and 'alpha level').
- Current compatibility with modern type checker versions and whether the accompanying mypy plugin is still maintained.
- Practical compatibility with PyPy, given the classifier lists it as supported.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 2.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy type stubs, sqlalchemy mypy typing, sqlalchemy 1.4 type hints, sqlalchemy static type checking, pep 484 sqlalchemy stubs, sqlalchemy type annotations, type-stubs, sqlalchemy-1.4, legacy

[View on SkillFed](https://skillfed.io/packages/sqlalchemy2-stubs) · [View on PyPI](https://pypi.org/project/sqlalchemy2-stubs/)