{"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":"python","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":[{"wrong":"from sqlalchemy-stubs import Column","symbol":"Column","correct":"from sqlalchemy_stubs import Column"}],"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\"\"\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,"search_vec":"'1':64 '2.0':68 '561':11 'activ':75 'analyz':37 'annot':72 'catch':46 'check':20,86 'checker':28 'code':38,43 'design':15 'develop':50 'enabl':26 'error':48 'improv':42 'integr':69 'librari':24 'maintain':76 'mypi':31,87 'nativ':70 'packag':14,53 'part':55,78 'pep':10 'potenti':47 'primarili':61 'project':59 'provid':17 'pycharm':35 'pyright':32,88 'pytyp':33 'qualiti':44 'sqlalchemi':4,7,23,41,63,67,83 'static':18 'stub':2,13,82 'support':62 'time':51 'type':1,6,12,19,27,71,81,85 'type-check':84 'types-sqlalchemi':5 'typesh':58,80,89 'use':40 'x':65","created_at":"2026-04-16T14:15:08.359667+00:00","updated_at":"2026-04-16T14:15:08.359667+00:00","problems":{"verify_error":"Traceback (most recent call last):\n File \"\", line 1, in \nModuleNotFoundError: No module named 'sqlalchemy_stubs'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4.53.38","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/SQLAlchemy.md","pypi":"https://pypi.org/project/types-sqlalchemy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}