Install & Compatibility
Where this runs
tested against v0.0.2a38 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.6s · import 0.000s · 20MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
declarative_base
✓ from sqlalchemy_stubs.ext.declarative import declarative_base
✗ from sqlalchemy_stubs.ext.declarative import declarative_base
This quickstart demonstrates defining a SQLAlchemy 1.4 ORM model with `sqlalchemy2-stubs` compatible type annotations using `Mapped`. The `sqlalchemy2-stubs` package itself does not have runtime code but provides type hints for tools like Mypy. Ensure Mypy is configured to use the SQLAlchemy plugin for full benefits (e.g., in `mypy.ini` or `pyproject.toml`: `[mypy]
plugins = sqlalchemy.ext.mypy.plugin`).
from typing import Optional
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import Mapped, declarative_base, Session
Base = declarative_base()
class User(Base):
__tablename__ = "users"
id: Mapped[int] = Column(Integer, primary_key=True)
name: Mapped[Optional[str]] = Column(String(50))
email: Mapped[str] = Column(String(50), nullable=False)
def __repr__(self) -> str:
return f"<User(id={self.id}, name='{self.name}', email='{self.email}')>"
# Example usage (not requiring sqlalchemy2-stubs at runtime, but for type checking)
if __name__ == '__main__':
engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)
with Session(engine) as session:
new_user = User(name='Alice', email='alice@example.com')
session.add(new_user)
session.commit()
print(f"Added user: {new_user}")
retrieved_user = session.query(User).filter_by(name='Alice').first()
print(f"Retrieved user: {retrieved_user}")
Debug
Known issues
breakingThe `sqlalchemy2-stubs` package is explicitly NOT compatible with SQLAlchemy 2.0. Upgrading to SQLAlchemy 2.0 requires manual uninstallation of `sqlalchemy2-stubs` because SQLAlchemy 2.0 includes inline type annotations that conflict with stub packages.fixBefore upgrading to SQLAlchemy 2.0, or if you are using SQLAlchemy 2.0, uninstall `sqlalchemy2-stubs` using `pip uninstall sqlalchemy2-stubs`.
affects: All versions of sqlalchemy2-stubs when used with SQLAlchemy 2.0+
deprecatedThe Mypy plugin associated with `sqlalchemy2-stubs` is deprecated in SQLAlchemy 2.0 and has known compatibility issues with Mypy versions 1.11.0 or greater, with support guaranteed only up to Mypy 1.10.1.fixFor SQLAlchemy 1.4, use Mypy versions 1.10.1 or older. For SQLAlchemy 2.0, migrate to its native typing system and remove the Mypy plugin and stubs.
affects: All versions of sqlalchemy2-stubs (for Mypy plugin compatibility)
gotchaDo not install `sqlalchemy2-stubs` and the older `sqlalchemy-stubs` (from Dropbox) simultaneously. They occupy the same namespace and will cause conflicts and incorrect type checking results.fixEnsure only one set of SQLAlchemy stubs (`sqlalchemy2-stubs` or `sqlalchemy-stubs`) is installed. For SQLAlchemy 1.4, `sqlalchemy2-stubs` is recommended.
affects: All versions
gotchaMixed environments (e.g., SQLAlchemy 1.x and 2.x codebases, or incremental migration attempts) where `sqlalchemy2-stubs` is present can lead to significant type errors, especially with imports like `declarative_base`.fixMaintain a clear separation of SQLAlchemy versions. For projects migrating to SQLAlchemy 2.0, a complete transition away from `sqlalchemy2-stubs` is necessary, and incremental migration with stubs installed is difficult and often problematic.
affects: All versions when used in mixed environments
Upgrade
Version history
0.0.2a38latest on PyPI · released Dec 30, 2023
Audit
Dependencies
sqlalchemy>=1.4,<2.0requiredThese stubs are specifically for SQLAlchemy 1.4.
mypyrequiredThe stubs are designed to work with Mypy for static type checking.