The mypy configuration file¶
Mypy supports reading configuration settings from a file. By default
it uses the file
mypy.ini with fallback to
setup.cfg in the current
.mypy.ini in the user home directory if none of them are
--config-file command-line flag can be used to read a different
file instead (see –config-file).
It is important to understand that there is no merging of configuration
files, as it would lead to ambiguity. The
has the highest precedence and must be correct; otherwise mypy will report
an error and exit. Without command line option, mypy will look for defaults,
but will use only one of them. The first one to read is
Most flags correspond closely to command-line flags but there are some differences in flag names and some flags may take a different value based on the module being processed.
The configuration file format is the usual
format. It should contain section names in square brackets and flag
settings of the form NAME = VALUE. Comments start with
A section named
[mypy]must be present. This specifies the global flags. The
setup.cfgfile is an exception to this.
Additional sections named
[mypy-PATTERN1,PATTERN2,...]may be present, where
PATTERN2, etc., are comma-separated patterns of fully-qualified module names, with some components optionally replaced by *`s (e.g. ``foo.bar`,
foo.*.baz). These sections specify additional flags that only apply to modules whose name matches at least one of the patterns.
A pattern of the form
qualified_module_namematches only the named module, while
dotted_module_nameand any submodules (so
foo.bar.*would match all of
Patterns may also be “unstructured” wildcards, in which stars may appear in the middle of a name (e.g
site.*.migrations.*). Stars match zero or more module components (so
- When options conflict, the precedence order for the configuration sections is:
- Sections with concrete module names (
- Sections with “unstructured” wildcard patterns (
foo.*.baz), with sections later in the configuration file overriding sections earlier.
- Sections with “well-structured” wildcard patterns
foo.bar.*), with more specific overriding more general.
- Command line options.
- Top-level configuration file options.
- Sections with concrete module names (
The difference in precedence order between “structured” patterns (by specificity) and “unstructured” patterns (by order in the file) is unfortunate, and is subject to change in future versions.
warn_unused_configs flag may be useful to debug misspelled
The following global flags may only be set in the global section
python_version(string) specifies the Python version used to parse and check the target program. The format is
2.7. The default is the version of the Python interpreter used to run mypy.
platform(string) specifies the OS platform for the target program, for example
win32(meaning OS X or Windows, respectively). The default is the current platform as revealed by Python’s
always_true(comma-separated list of strings) gives variable names that will be treated as compile-time constants that are always true.
always_false(comma-separated list of strings) gives variable names that will be treated as compile-time constants that are always false.
custom_typing_module(string) specifies the name of an alternative module which is to be considered equivalent to the
custom_typeshed_dir(string) specifies the name of an alternative directory which is used to look for stubs instead of the default
mypy_path(string) specifies the paths to use, after trying the paths from
MYPYPATHenvironment variable. Useful if you’d like to keep stubs in your repo, along with the config file.
warn_incomplete_stub(Boolean, default False) warns for missing type annotation in typeshed. This is only relevant in combination with
warn_redundant_casts(Boolean, default False) warns about casting an expression to its inferred type.
warn_unused_configs(Boolean, default False) warns about per-module sections in the config file that didn’t match any files processed in the current run.
scripts_are_modules(Boolean, default False) makes script
__main__. This is useful when checking multiple scripts in a single run.
verbosity(integer, default 0) controls how much debug output will be generated. Higher numbers are more verbose.
pdb(Boolean, default False) invokes pdb on fatal error.
show_traceback(Boolean, default False) shows traceback on fatal error.
dump_type_stats(Boolean, default False) dumps stats about type definitions.
dump_inference_stats(Boolean, default False) dumps stats about type inference.
incremental(Boolean, default True) enables incremental mode.
.mypy_cache) stores module cache info in the given folder in incremental mode. The cache is only read in incremental mode, but it is always written unless the value is set to
quick_and_dirty(Boolean, default False) enables quick mode.
show_error_context(Boolean, default False) shows context notes before errors.
show_column_numbers(Boolean, default False) shows column numbers in error messages.
The following flags may vary per module. They may also be specified in the global section; the global section provides defaults which are overridden by the pattern sections matching the module name.
If multiple pattern sections match a module, the options from the
most specific section are used where they disagree. This means
foo.bar will take values from sections with the patterns
foo.*, but when they specify
different values, it will use values from
normal) directs what to do with imports when the imported module is found as a
.pyfile and not part of the files, modules and packages on the command line. The four possible values are
error. For explanations see the discussion for the –follow-imports command line flag. Note that if pattern matching is used, the pattern should match the name of the imported module, not the module containing the import statement.
follow_imports_for_stubs(Boolean, default false) determines whether to respect the
follow_importssetting even for stub (
.pyi) files. Used in conjunction with
follow_imports=skip, this can be used to suppress the import of a module from
typeshed, replacing it with Any. Used in conjunction with
follow_imports=error, this can be used to make any use of a particular
typeshedmodule an error.
ignore_missing_imports(Boolean, default False) suppress error messages about imports that cannot be resolved. Note that if pattern matching is used, the pattern should match the name of the imported module, not the module containing the import statement.
silent_imports(Boolean, deprecated) equivalent to
almost_silent(Boolean, deprecated) equivalent to
strict_optional(Boolean, default True) enables or disables strict Optional checks. If False, mypy treats
Noneas compatible with every type.
Note: This was False by default in mypy versions earlier than 0.600.
disallow_any_unimported(Boolean, default false) disallows usage of types that come from unfollowed imports (such types become aliases for
disallow_any_expr(Boolean, default false) disallows all expressions in the module that have type
disallow_any_decorated(Boolean, default false) disallows functions that have
Anyin their signature after decorator transformation.
disallow_any_explicit(Boolean, default false) disallows explicit
Anyin type positions such as type annotations and generic type parameters.
disallow_any_generics(Boolean, default false) disallows usage of generic types that do not specify explicit type parameters.
disallow_incomplete_defs(Boolean, default false) disallow defining functions with incomplete type annotations. See –disallow-incomplete-defs option.
disallow_subclassing_any(Boolean, default False) disallows subclassing a value of type
Any. See –disallow-subclassing-any option.
disallow_untyped_calls(Boolean, default False) disallows calling functions without type annotations from functions with type annotations.
disallow_untyped_defs(Boolean, default False) disallows defining functions without type annotations or with incomplete type annotations.
check_untyped_defs(Boolean, default False) type-checks the interior of functions without type annotations.
debug_cache(Boolean, default False) writes the incremental cache JSON files using a more readable, but slower format.
show_none_errors(Boolean, default True) shows errors related to strict
Nonechecking, if the global
strict_optionalflag is enabled.
ignore_errors(Boolean, default False) ignores all non-fatal errors.
warn_no_return(Boolean, default True) shows errors for missing return statements on some execution paths.
warn_return_any(Boolean, default False) shows a warning when returning a value with type
Anyfrom a function declared with a non-
warn_unused_ignores(Boolean, default False) warns about unneeded
# type: ignorecomments.
strict_boolean(Boolean, default False) makes using non-boolean expressions in conditions an error.
no_implicit_optional(Boolean, default false) changes the treatment of arguments with a default value of None by not implicitly making their type Optional
You might put this in your
mypy.ini file at the root of your repo:
[mypy] python_version = 2.7 [mypy-foo.*] disallow_untyped_defs = True
This automatically sets
--python-version 2.7 (a.k.a.
for all mypy runs in this tree, and also selectively turns on the
--disallow-untyped-defs flag for all modules in the
package. This issues an error for function definitions without
type annotations in that subdirectory only.
If you would like to ignore specific imports, instead of ignoring all missing
--ignore-missing-imports, use a section of the configuration
file per module such as the following to ignore missing imports from
[mypy-lib_module] ignore_missing_imports = True
Configuration flags are liable to change between releases.