Programming language: Python

typeshed alternatives and similar packages

Based on the "awesome-python-typing" category

Do you think we are missing an alternative of typeshed or a related project?

Add another 'awesome-python-typing' Package



Build Status Chat at https://gitter.im/python/typing Pull Requests Welcome


Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people external to those projects.

This data can e.g. be used for static analysis, type checking or type inference.

For information on how to use typeshed, read below. Information for contributors can be found in [CONTRIBUTING.md](CONTRIBUTING.md). Please read it before submitting pull requests; do not report issues with annotations to the project the stubs are for, but instead report them here to typeshed.

Typeshed supports Python versions 2.7 and 3.5 and up.


If you're just using mypy (or pytype or PyCharm), as opposed to developing it, you don't need to interact with the typeshed repo at all: a copy of typeshed is bundled with mypy.

When you use a checked-out clone of the mypy repo, a copy of typeshed should be included as a submodule, using

$ git clone --recurse-submodules https://github.com/python/mypy.git


$ git clone https://github.com/python/mypy.git
$ cd mypy
$ git submodule init
$ git submodule update

and occasionally you will have to repeat the final command (git submodule update) to pull in changes made in the upstream typeshed repo.

PyCharm and pytype similarly include a copy of typeshed. The one in pytype can be updated in the same way if you are working with the pytype repo.


Each Python module is represented by a .pyi "stub file". This is a syntactically valid Python file, although it usually cannot be run by Python 3 (since forward references don't require string quotes). All the methods are empty.

Python function annotations (PEP 3107) are used to describe the signature of each function or method.

See PEP 484 for the exact syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the coding style used in typeshed.

Directory structure


This contains stubs for modules the Python standard library -- which includes pure Python modules, dynamically loaded extension modules, hard-linked extension modules, and the builtins.


Modules that are not shipped with Python but have a type description in Python go into third_party. Since these modules can behave differently for different versions of Python, third_party has version subdirectories, just like stdlib.

For more information on directory structure and stub versioning, see the relevant section of CONTRIBUTING.md.


Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests. If you have questions related to contributing, drop by the typing Gitter.

Running the tests

The tests are automatically run by Travis CI on every PR and push to the repo. There are several sets of tests: tests/mypy_test.py runs tests against mypy, while tests/pytype_test.py runs tests against pytype.

Both sets of tests are shallow -- they verify that all stubs can be imported but they don't check whether stubs match their implementation (in the Python standard library or a third-party package). Also note that each set of tests has a blacklist of modules that are not tested at all. The blacklists also live in the tests directory.

In addition, you can run tests/mypy_selftest.py to run mypy's own test suite using the typeshed code in your repo. This will sometimes catch issues with incorrectly typed stubs, but is much slower than the other tests.

To manually run the mypy tests, you need to have Python 3.5 or higher; Python 3.6.1 or higher is recommended.


$ python3.6 -m venv .venv3
$ source .venv3/bin/activate
(.venv3)$ pip3 install -r requirements-tests-py3.txt

This will install mypy (you need the latest master branch from GitHub), typed-ast, flake8, and pytype. You can then run mypy, flake8, and pytype tests by invoking:

(.venv3)$ python3 tests/mypy_test.py
(.venv3)$ python3 tests/mypy_selftest.py
(.venv3)$ flake8
(.venv3)$ python3 tests/pytype_test.py

Note that flake8 only works with Python 3.6 or higher, and that to run the pytype tests, you will need Python 2.7 and Python 3.6 interpreters. Pytype will find these automatically if they're in PATH, but otherwise you must point to them with the --python27-exe and --python36-exe arguments, respectively.

For mypy, if you are in the typeshed repo that is submodule of the mypy repo (so .. refers to the mypy repo), there's a shortcut to run the mypy tests that avoids installing mypy:

$ PYTHONPATH=../.. python3 tests/mypy_test.py

You can mypy tests to a single version by passing -p2 or -p3.5 e.g.

$ PYTHONPATH=../.. python3 tests/mypy_test.py -p3.5
running mypy --python-version 3.5 --strict-optional # with 342 files