Install & Compatibility
Where this runs
tested against v0.4 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 83.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.000s · 81MB
80MB installed
● package 80MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Plugin Configuration
✓ [mypy]
plugins = sqlmypy
This is a Mypy configuration entry, not a Python import. It must be added to your 'mypy.ini' or 'setup.cfg' to enable the plugin.
This quickstart demonstrates how to define a SQLAlchemy declarative model. To benefit from `sqlalchemy-stubs`, you must install the package and configure Mypy to use its plugin by adding `plugins = sqlmypy` to your `mypy.ini` or `setup.cfg` file. Run Mypy separately on your project to enable static type checking for SQLAlchemy models.
import os
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, sessionmaker
# Configure Mypy (typically in mypy.ini or setup.cfg, not code)
# [mypy]
# plugins = sqlmypy
# Database setup (example using SQLite in memory)
DATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///:memory:')
engine = create_engine(DATABASE_URL)
Base = declarative_base()
Session = sessionmaker(bind=engine)
class User(Base):
__tablename__ = 'users'
id: int = Column(Integer, primary_key=True)
name: str = Column(String)
# This class will be type-checked by mypy using the stubs and plugin
# (Assuming mypy is configured and run externally)
# Example usage (not directly type-checked by sqlalchemy-stubs at runtime)
def create_user(session, user_id: int, user_name: str):
new_user = User(id=user_id, name=user_name)
session.add(new_user)
session.commit()
return new_user
if __name__ == '__main__':
Base.metadata.create_all(engine)
session = Session()
# This part needs mypy run externally to show type benefits
# For instance, mypy might catch: create_user(session, '1', 123) if types were incorrect
user1 = create_user(session, 1, 'Alice')
print(f"Created user: {user1.name} (ID: {user1.id})")
session.close()
Debug
Known issues
breakingThe `sqlalchemy-stubs` package is superseded by SQLAlchemy 2.0's native, inline type annotations. Installing `sqlalchemy-stubs` or `sqlalchemy2-stubs` (for SQLAlchemy 1.4) can cause type conflicts and incorrect behavior with SQLAlchemy 2.0+.fixFor SQLAlchemy 2.0+, uninstall `sqlalchemy-stubs` and `sqlalchemy2-stubs` (if installed). SQLAlchemy 2.0 provides full PEP-484 compliant typing natively without external stub packages or a Mypy plugin.
affects: SQLAlchemy 2.0.0 and newer
deprecatedThis project (version 0.4) is no longer actively maintained and has not seen updates since January 2021. Its functionality has been largely replaced by the SQLAlchemy project's own typing efforts.fixTransition to SQLAlchemy 2.0+ for native typing support. If using SQLAlchemy 1.4, consider the `sqlalchemy2-stubs` package (though also superseded by 2.0+).
affects: All versions
gotchaThe Mypy plugin provided by `sqlalchemy-stubs` must be explicitly enabled in your Mypy configuration file (e.g., `mypy.ini` or `setup.cfg`) via `plugins = sqlmypy`. Without this, the stubs will not provide enhanced type inference.fixEnsure your Mypy configuration includes the `plugins = sqlmypy` line under the `[mypy]` section.
affects: All versions of `sqlalchemy-stubs`
gotchaThe `sqlalchemy-stubs` package is marked as 'Alpha' and may not fully cover all SQLAlchemy features or edge cases, potentially leading to incomplete type inference (`Any`) or false positive errors.fixBe aware of potential limitations. For more comprehensive and up-to-date typing, upgrading to SQLAlchemy 2.0+ is the recommended approach.
affects: All versions of `sqlalchemy-stubs`
Upgrade
Version history
0.4latest on PyPI · released Jan 12, 2021
Audit
Dependencies
mypyrequiredRequired to use the Mypy plugin for type checking.
typing-extensionsrequiredRequired for type hint features.
SQLAlchemyrequiredThe core library that these stubs provide typing for. Must be installed separately.