Using installed packages with mypy (PEP 561)¶

Typically mypy will automatically find and use installed packages thatsupport type checking or provide stubs. This requires that you installthe packages in the Python environment that you use to run mypy. Asmany packages don’t support type checking yet, you may also have toinstall a separate stub package, usually namedtypes-<library>. (SeeMissing imports for how to dealwith libraries that don’t support type checking and are also missingstubs.)

If you have installed typed packages in another Python installation orenvironment, mypy won’t automatically find them. One option is toinstall another copy of those packages in the environment in which youinstalled mypy. Alternatively, you can use the--python-executable flag to pointto the Python executable for another environment, and mypy will findpackages installed for that Python executable.

Note that mypy does not support some more advanced import features,such as zip imports and custom import hooks.

If you don’t want to use installed packages that provide typeinformation at all, use the--no-site-packages flag to disable searching for installed packages.

Note that stub-only packages cannot be used withMYPYPATH. If youwant mypy to find the package, it must be installed. For a packagefoo, the name of the stub-only package (foo-stubs) is not alegal package name, so mypy will not find it, unless it is installed(seePEP 561: Stub-only Packages formore information).

Creating PEP 561 compatible packages¶

PEP 561 describes three main ways to distribute typeinformation:

1. A package has inline type annotations in the Python implementation.

2. A package shipsstub files with typeinformation alongside the Python implementation.

3. A package ships type information for another package separately asstub files (also known as a “stub-only package”).

If you want to create a stub-only package for an existing library, thesimplest way is to contribute stubs to thetypeshed repository, and a stub packagewill automatically be uploaded to PyPI.

If you would like to publish a library package to a package repositoryyourself (e.g. on PyPI) for either internal or external use in typechecking, packages that supply type information via type comments orannotations in the code should put apy.typed file in theirpackage directory. For example, here is a typical directory structure:

setup.pypackage_a/    __init__.py    lib.py    py.typed

Thesetup.py file could look like this:

fromsetuptoolsimportsetupsetup(name="SuperPackageA",author="Me",version="0.1",package_data={"package_a":["py.typed"]},packages=["package_a"])

Some packages have a mix of stub files and runtime files. These packages alsorequire apy.typed file. An example can be seen below:

setup.pypackage_b/    __init__.py    lib.py    lib.pyi    py.typed

Thesetup.py file might look like this:

fromsetuptoolsimportsetupsetup(name="SuperPackageB",author="Me",version="0.1",package_data={"package_b":["py.typed","lib.pyi"]},packages=["package_b"])

In this example, bothlib.py and thelib.pyi stub file exist. Atruntime, the Python interpreter will uselib.py, but mypy will uselib.pyi instead.

If the package is stub-only (not imported at runtime), the package should havea prefix of the runtime package name and a suffix of-stubs.Apy.typed file is not needed for stub-only packages. For example, if wehad stubs forpackage_c, we might do the following:

setup.pypackage_c-stubs/    __init__.pyi    lib.pyi

Thesetup.py might look like this:

fromsetuptoolsimportsetupsetup(name="SuperPackageC",author="Me",version="0.1",package_data={"package_c-stubs":["__init__.pyi","lib.pyi"]},packages=["package_c-stubs"])

The instructions above are enough to ensure that the built wheelscontain the appropriate files. However, to ensure inclusion inside thesdist (.tar.gz archive), you may also need to modify theinclusion rules in yourMANIFEST.in:

global-include *.pyiglobal-include *.typed