Typeshed is a collection of library stubs for Python that provides external type annotations for the Python standard library, builtins, and third-party packages.
Typeshed solves the problem of enabling static type checking, type inference, and autocompletion for Python code when the original libraries lack built-in type information. It works by maintaining stub files—type annotation files separate from the runtime code—that describe the types of functions, classes, and variables in Python libraries. These stubs are used by type checkers like mypy, pyright, and PyCharm to understand the types available in both standard library and third-party packages without requiring changes to those libraries themselves.
Most Python developers do not need to interact with the typeshed repository directly. Type checkers bundle a copy of the standard library stubs automatically, and third-party package stubs are distributed as separate PyPI packages that type checkers discover when installed. The tool suits anyone using a type checker who wants accurate type information for libraries they depend on. Third-party stub packages follow a versioning scheme where the first parts of the version number correspond to the runtime package version, allowing developers to pin stubs to versions compatible with their dependencies. The project acknowledges that stub versions can introduce breaking changes despite efforts to minimize them, and documents strategies for managing stub package versions alongside the packages they annotate.
The project maintains active engagement with contributors through clear contribution guidelines and processes pull requests for stub improvements. Development spans support across multiple Python versions from 3.10 through 3.14. The project operates an automated release system that publishes updated third-party stubs to PyPI daily, ensuring that type information stays current with library changes. Typeshed explicitly directs users to report annotation issues to the typeshed repository rather than to the original library projects, establishing itself as the canonical source for type stub maintenance.
