Install & Compatibility
Where this runs
tested against v1.4.53.38 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Column
✓ from sqlalchemy_stubs import Column
✗ from sqlalchemy-stubs import Column
This quickstart demonstrates a basic SQLAlchemy declarative model with type hints. When `types-sqlalchemy` is installed, a static type checker (like MyPy) can analyze this code to ensure type correctness for SQLAlchemy constructs (e.g., `Column`, `String`, `Mapped`). For SQLAlchemy 2.0+, native typing is available and recommended over external stubs.
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, sessionmaker
from typing import Optional
# types-sqlalchemy provides stubs that enable type checkers
# to understand the types of SQLAlchemy objects like Column, String, etc.
Base = declarative_base()
class User(Base):
__tablename__ = 'users'
id: Mapped[int] = mapped_column(Integer, primary_key=True)
name: Mapped[str] = mapped_column(String)
email: Mapped[Optional[str]] = mapped_column(String, nullable=True)
def __repr__(self) -> str:
return f"<User(id={self.id}, name='{self.name}', email='{self.email}')>"
# Example usage (runtime, type-checked by types-sqlalchemy)
# In a real application, you would typically use an environment variable for the connection string
DATABASE_URL = "sqlite:///:memory:"
engine = create_engine(DATABASE_URL)
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()
new_user = User(name='Alice', email='alice@example.com')
session.add(new_user)
session.commit()
retrieved_user: Optional[User] = session.query(User).filter_by(name='Alice').first()
if retrieved_user:
print(retrieved_user) # type: ignore
session.close()
Debug
Known issues
breakingSQLAlchemy versions 2.0 and newer include native type annotations. Using `types-sqlalchemy` alongside SQLAlchemy 2.0+ can lead to conflicts and incorrect type checking results. It is strongly recommended to uninstall `types-sqlalchemy` if you are using SQLAlchemy 2.0 or a newer version and rely on SQLAlchemy's built-in typing.fixUninstall `types-sqlalchemy` using `pip uninstall types-sqlalchemy`. Consult SQLAlchemy's official documentation for 2.0+ native typing guidance.
affects: SQLAlchemy >= 2.0
gotchaThere are alternative SQLAlchemy stub packages, notably `sqlalchemy-stubs`. While `types-sqlalchemy` is part of the official `typeshed` project and is plugin-agnostic, `sqlalchemy-stubs` provides a MyPy plugin for potentially more precise type inference in some complex cases. Choose one based on your specific type-checking needs and tooling.fixReview the documentation for both `types-sqlalchemy` (part of typeshed) and `sqlalchemy-stubs` to decide which best fits your project's requirements, especially if using a MyPy plugin is beneficial. Avoid installing both simultaneously.
affects: All versions
gotchaContributions and fixes for `types-sqlalchemy` should be made directly to the `typeshed` repository on GitHub (`https://github.com/python/typeshed/tree/main/stubs/SQLAlchemy`), not to the `types-sqlalchemy` PyPI project directly.fixTo report issues or contribute type fixes, open a pull request or issue against the relevant stub directory within the `typeshed` GitHub repository.
affects: All versions
Upgrade
Version history
1.4.53.38latest on PyPI · released May 1, 2023
Audit
Dependencies
SQLAlchemyrequiredThis package provides type stubs for SQLAlchemy; SQLAlchemy itself must be installed to use these stubs for type checking.