{"id":7828,"library":"types-sqlalchemy","title":"Typing Stubs for SQLAlchemy","description":"types-sqlalchemy is a PEP 561 type stub package designed to provide static type checking for the SQLAlchemy library. It enables type checkers such as MyPy, Pyright, Pytype, and PyCharm to analyze code that uses SQLAlchemy, improving code quality and catching potential errors at development time. This package is part of the `typeshed` project and primarily supports SQLAlchemy 1.x, with SQLAlchemy 2.0+ integrating native type annotations. It is actively maintained as part of typeshed.","status":"active","version":"1.4.53.38","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/SQLAlchemy","tags":["typing","stubs","sqlalchemy","type-checking","mypy","pyright","typeshed"],"install":[{"cmd":"pip install types-sqlalchemy","lang":"bash","label":"Install types-sqlalchemy"}],"dependencies":[{"reason":"This package provides type stubs for SQLAlchemy; SQLAlchemy itself must be installed to use these stubs for type checking.","package":"SQLAlchemy","optional":false}],"imports":[{"note":"The `types-sqlalchemy` package does not provide any symbols for direct runtime import. Its purpose is to add type annotations to existing `sqlalchemy` imports, enabling static type checking.","symbol":"SQLAlchemy imports (e.g., Column, String, declarative_base)","correct":"from sqlalchemy import Column, Integer, String\nfrom sqlalchemy.orm import declarative_base, Mapped, mapped_column\nfrom typing import Optional"}],"quickstart":{"code":"from sqlalchemy import create_engine, Column, Integer, String\nfrom sqlalchemy.orm import declarative_base, sessionmaker\nfrom typing import Optional\n\n# types-sqlalchemy provides stubs that enable type checkers\n# to understand the types of SQLAlchemy objects like Column, String, etc.\n\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = 'users'\n    id: Mapped[int] = mapped_column(Integer, primary_key=True)\n    name: Mapped[str] = mapped_column(String)\n    email: Mapped[Optional[str]] = mapped_column(String, nullable=True)\n\n    def __repr__(self) -> str:\n        return f\"<User(id={self.id}, name='{self.name}', email='{self.email}')>\"\n\n# Example usage (runtime, type-checked by types-sqlalchemy)\n# In a real application, you would typically use an environment variable for the connection string\nDATABASE_URL = \"sqlite:///:memory:\"\nengine = create_engine(DATABASE_URL)\nBase.metadata.create_all(engine)\n\nSession = sessionmaker(bind=engine)\nsession = Session()\n\nnew_user = User(name='Alice', email='alice@example.com')\nsession.add(new_user)\nsession.commit()\n\nretrieved_user: Optional[User] = session.query(User).filter_by(name='Alice').first()\nif retrieved_user:\n    print(retrieved_user) # type: ignore\n\nsession.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Uninstall `types-sqlalchemy` using `pip uninstall types-sqlalchemy`. Consult SQLAlchemy's official documentation for 2.0+ native typing guidance.","message":"SQLAlchemy 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.","severity":"breaking","affected_versions":"SQLAlchemy >= 2.0"},{"fix":"Review 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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To report issues or contribute type fixes, open a pull request or issue against the relevant stub directory within the `typeshed` GitHub repository.","message":"Contributions 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Uninstall `types-sqlalchemy` via `pip uninstall types-sqlalchemy`. Ensure your SQLAlchemy version is 2.0 or newer and rely on its built-in typing. If you need 1.x stubs, ensure SQLAlchemy is also 1.x.","cause":"This typically occurs when `types-sqlalchemy` is installed alongside SQLAlchemy 2.0+, which has its own native type annotations, leading to conflicting stub definitions.","error":"mypy: Duplicate module named 'sqlalchemy' (or similar errors with type conflicts)"},{"fix":"Adjust the value being assigned to match the expected type hint (e.g., change `name=42` to `name='John Doe'`). Review your model definitions and assignments to ensure type consistency.","cause":"This indicates a type mismatch in your code where a value of an incorrect type is being assigned to a SQLAlchemy column that has been type-hinted. For example, assigning an integer to a string column.","error":"Incompatible type for \"name\" of \"User\" (got \"int\", expected \"Optional[str]\")"}]}