Specifying code to be checked¶

Mypy lets you specify what files it should type check in several different ways.

1. First, you can pass in paths to Python files and directories youwant to type check. For example:

   $ mypy file_1.py foo/file_2.py file_3.pyi some/directory

   The above command tells mypy it should type check all of the providedfiles together. In addition, mypy will recursively type check theentire contents of any provided directories.

   For more details about how exactly this is done, seeMapping file paths to modules.

2. Second, you can use the-m flag (long form:--module) tospecify a module name to be type checked. The name of a moduleis identical to the name you would use to import that modulewithin a Python program. For example, running:

   $ mypy -m html.parser

   …will type check the modulehtml.parser (this happens to bea library stub).

   Mypy will use an algorithm very similar to the one Python uses tofind where modules and imports are located on the file system.For more details, seeHow imports are found.

3. Third, you can use the-p (long form:--package) flag tospecify a package to be (recursively) type checked. This flagis almost identical to the-m flag except that if you give ita package name, mypy will recursively type check all submodulesand subpackages of that package. For example, running:

   $ mypy -p html

   …will type check the entirehtml package (of library stubs).In contrast, if we had used the-m flag, mypy would have typechecked justhtml’s__init__.py file and anything importedfrom there.

   Note that we can specify multiple packages and modules on thecommand line. For example:

   $ mypy --package p.a --package p.b --module c

4. Fourth, you can also instruct mypy to directly type check smallstrings as programs by using the-c (long form:--command)flag. For example:

   $ mypy -c 'x = [1, 2]; print(x())'

   …will type check the above string as a mini-program (and in this case,will report thatlist[int] is not callable).

You can also use thefiles option in yourmypy.ini file to specify whichfiles to check, in which case you can simply runmypy with no arguments.

Reading a list of files from a file¶

Finally, any command-line argument starting with@ reads additionalcommand-line arguments from the file following the@ character.This is primarily useful if you have a file containing a list of filesthat you want to be type-checked: instead of using shell syntax like:

$ mypy $(cat file_of_files.txt)

you can use this instead:

$ mypy @file_of_files.txt

This file can technically also contain any command line flag, notjust file paths. However, if you want to configure many differentflags, the recommended approach is to use aconfiguration file instead.

Mapping file paths to modules¶

One of the main ways you can tell mypy what to type checkis by providing mypy a list of paths. For example:

$ mypy file_1.py foo/file_2.py file_3.pyi some/directory

This section describes how exactly mypy maps the provided pathsto modules to type check.

• Mypy will check all paths provided that correspond to files.

• Mypy will recursively discover and check all files ending in.py or.pyi in directory paths provided, after accounting for--exclude.

• For each file to be checked, mypy will attempt to associate the file (e.g.project/foo/bar/baz.py) with a fully qualified module name (e.g.foo.bar.baz). The directory the package is in (project) is thenadded to mypy’s module search paths.

How mypy determines fully qualified module names depends on if the options--no-namespace-packages and--explicit-package-bases are set.

1. If--no-namespace-packages is set,mypy will rely solely upon the presence of__init__.py[i] files todetermine the fully qualified module name. That is, mypy will crawl up thedirectory tree for as long as it continues to find__init__.py (or__init__.pyi) files.

   For example, if your directory tree consists ofpkg/subpkg/mod.py, mypywould requirepkg/__init__.py andpkg/subpkg/__init__.py to exist inorder correctly associatemod.py withpkg.subpkg.mod

2. The default case. If--namespace-packages is on, but--explicit-package-bases is off, mypy will allow for the possibility thatdirectories without__init__.py[i] are packages. Specifically, mypy willlook at all parent directories of the file and use the location of thehighest__init__.py[i] in the directory tree to determine the top-levelpackage.

   For example, say your directory tree consists solely ofpkg/__init__.pyandpkg/a/b/c/d/mod.py. When determiningmod.py’s fully qualifiedmodule name, mypy will look atpkg/__init__.py and conclude that theassociated module name ispkg.a.b.c.d.mod.

3. You’ll notice that the above case still relies on__init__.py. Ifyou can’t put an__init__.py in your top-level package, but still wish topass paths (as opposed to packages or modules using the-p or-mflags),--explicit-package-basesprovides a solution.

   With--explicit-package-bases, mypywill locate the nearest parent directory that is a member of theMYPYPATHenvironment variable, themypy_path config or is the currentworking directory. Mypy will then use the relative path to determine thefully qualified module name.

   For example, say your directory tree consists solely ofsrc/namespace_pkg/mod.py. If you run the following command, mypywill correctly associatemod.py withnamespace_pkg.mod:

   $ MYPYPATH=src mypy --namespace-packages --explicit-package-bases .

If you pass a file not ending in.py[i], the module name assumed is__main__ (matching the behavior of the Python interpreter), unless--scripts-are-modules is passed.

Passing-v will show you the files and associated modulenames that mypy will check.

How mypy handles imports¶

When mypy encounters animport statement, it will firstattempt to locate that moduleor type stubs for that module in the file system. Mypy will thentype check the imported module. There are three different outcomesof this process:

1. Mypy is unable to follow the import: the module either does notexist, or is a third party library that does not use type hints.

2. Mypy is able to follow and type check the import, but you didnot want mypy to type check that module at all.

3. Mypy is able to successfully both follow and type check themodule, and you want mypy to type check that module.

The third outcome is what mypy will do in the ideal case. The followingsections will discuss what to do in the other two cases.

Missing imports¶

When you import a module, mypy may report that it is unable to followthe import. This can cause errors that look like the following:

main.py:1: error: Skipping analyzing 'django': module is installed, but missing library stubs or py.typed markermain.py:2: error: Library stubs not installed for "requests"main.py:3: error: Cannot find implementation or library stub for module named "this_module_does_not_exist"

If you get any of these errors on an import, mypy will assume the type of thatmodule isAny, the dynamic type. This means attempting to access anyattribute of the module will automatically succeed:

# Error: Cannot find implementation or library stub for module named 'does_not_exist'importdoes_not_exist# But this type checks, and x will have type 'Any'x=does_not_exist.foobar()

This can result in mypy failing to warn you about errors in your code. Sinceoperations onAny result inAny, these dynamic types can propagatethrough your code, making type checking less effective. SeeDynamically typed code for more information.

The next sections describe what each of these errors means and recommended next steps; scroll tothe section that matches your error.

main.py:1: error: Library stubs not installed for "yaml"main.py:1: note: Hint: "python3 -m pip install types-PyYAML"main.py:1: note: (or run "mypy --install-types" to install all missing stub packages)

mypy --install-types

How imports are found¶

When mypy encounters animport statement or receives modulenames from the command line via the--module or--packageflags, mypy tries to find the module on the file system similarto the way Python finds it. However, there are some differences.

First, mypy has its own search path.This is computed from the following items:

• TheMYPYPATH environment variable(a list of directories, colon-separated on UNIX systems, semicolon-separated on Windows).

• Themypy_path config file option.

• The directories containing the sources given on the command line(seeMapping file paths to modules).

• The installed packages marked as safe for type checking (seePEP 561 support)

• The relevant directories of thetypeshed repo.

Second, mypy searches for stub files in addition to regular Python filesand packages.The rules for searching for a modulefoo are as follows:

• The search looks in each of the directories in the search path(see above) until a match is found.

• If a package namedfoo is found (i.e. a directoryfoo containing an__init__.py or__init__.pyi file)that’s a match.

• If a stub file namedfoo.pyi is found, that’s a match.

• If a Python module namedfoo.py is found, that’s a match.

These matches are tried in order, so that if multiple matches are foundin the same directory on the search path(e.g. a package and a Python file, or a stub file and a Python file)the first one in the above list wins.

In particular, if a Python file and a stub file are both present in thesame directory on the search path, only the stub file is used.(However, if the files are in different directories, the one foundin the earlier directory is used.)

Settingmypy_path/MYPYPATH is mostly useful in the casewhere you want to try running mypy against multiple distinctsets of files that happen to share some common dependencies.

For example, if you have multiple projects that happen to beusing the same set of work-in-progress stubs, it could beconvenient to just have yourMYPYPATH point to a singledirectory containing the stubs.

Following imports¶

Mypy is designed todoggedly follow all imports,even if the imported module is not a file you explicitly wanted mypy to check.

For example, suppose we have two modulesmycode.foo andmycode.bar:the former has type hints and the latter does not. We runmypy-mmycode.foo and mypy discovers thatmycode.foo importsmycode.bar.

How do we want mypy to type checkmycode.bar? Mypy’s behaviour here isconfigurable – although westrongly recommend using the default –by using the--follow-imports flag. This flagaccepts one of four string values:

• normal (the default, recommended) follows all imports normally andtype checks all top level code (as well as the bodies of allfunctions and methods with at least one type annotation inthe signature).

• silent behaves in the same way asnormal but willadditionallysuppress any error messages.

• skip willnot follow imports and instead will silentlyreplace the module (andanything imported from it) with anobject of typeAny.

• error behaves in the same way asskip but is not quite assilent – it will flag the import as an error, like this:

  main.py:1:note:Importof"mycode.bar"ignoredmain.py:1:note:(Using--follow-imports=error,modulenotpassedoncommandline)

If you are starting a new codebase and plan on using type hints fromthe start, werecommend you use either--follow-imports=normal(the default) or--follow-imports=error. Either option will helpmake sure you are not skipping checking any part of your codebase byaccident.

If you are planning on adding type hints to a large, existing code base,we recommend you start by trying to make your entire codebase (includingfiles that do not use type hints) pass under--follow-imports=normal.This is usually not too difficult to do: mypy is designed to report asfew error messages as possible when it is looking at unannotated code.

Only if doing this is intractable, try passing mypy just the filesyou want to type check and using--follow-imports=silent.Even if mypy is unable to perfectly type check a file, it can still glean someuseful information by parsing it (for example, understanding what methodsa given object has). SeeUsing mypy with an existing codebase for more recommendations.

Adjusting import following behaviour is often most useful when restricted tospecific modules. This can be accomplished by setting a per-modulefollow_imports config option.