mypy

Main mypy type checker command-line interface

The mypy command is the main entry point for type checking Python code. It analyzes your code statically and reports type errors without running the code.

Basic usage

mypy program.py
mypy src/ tests/
mypy -m mymodule
mypy -p mypackage

Specifying what to check

files · string

Paths to files or directories to type check. Directories are checked recursively.

-m MODULE · string

Type-check the provided module. This flag may be repeated multiple times.

Mypy will not recursively type check submodules.

-p PACKAGE · string

Type-check the provided package recursively. This flag may be repeated.

Mypy will recursively type check all submodules of the provided package.

-c PROGRAM_TEXT · string

Type-check the provided string as a program.

General options

-h, --help · boolean

Show help message and exit.

-v, --verbose · boolean

More verbose messages. Can be repeated for increased verbosity.

-V, --version · boolean

Show program’s version number and exit.

-O FORMAT, --output FORMAT · string

Set a custom output format. Choices: json

Default: text output

Config file

--config-file CONFIG_FILE · string

Configuration file with [mypy] section.

Default: mypy.ini, .mypy.ini, pyproject.toml, or setup.cfg in current directory

--warn-unused-configs · boolean

Warn about unused [mypy-<pattern>] or [[tool.mypy.overrides]] config sections.

Import discovery

--ignore-missing-imports · boolean

Silently ignore imports of missing modules.

Default: false

--follow-untyped-imports · boolean

Typecheck modules without stubs or py.typed marker.

Default: false

--follow-imports · string

How to treat imports.

Choices: normal, silent, skip, error

Default: normal

--python-executable EXECUTABLE · string

Python executable used for finding PEP 561 compliant packages and stubs.

--no-site-packages · boolean

Do not search for installed PEP 561 compliant packages.

Default: false

--no-namespace-packages · boolean

Disable support for namespace packages (PEP 420, init.py-less).

Default: false (namespace packages enabled)

Platform configuration

--python-version X.Y · string

Type check code assuming it will be running on Python X.Y.

Example: --python-version 3.11

--platform PLATFORM · string

Type check special-cased code for the given OS platform.

Default: sys.platform

--always-true NAME · string

Additional variable to be considered True. May be repeated.

--always-false NAME · string

Additional variable to be considered False. May be repeated.

Disallow dynamic typing

--disallow-any-unimported · boolean

Disallow Any types resulting from unfollowed imports.

Default: false

--disallow-any-expr · boolean

Disallow all expressions that have type Any.

Default: false

--disallow-any-decorated · boolean

Disallow functions that have Any in their signature after decorator transformation.

Default: false

--disallow-any-explicit · boolean

Disallow explicit Any in type positions.

Default: false

--disallow-any-generics · boolean

Disallow usage of generic types that do not specify explicit type parameters.

Default: false

--disallow-subclassing-any · boolean

Disallow subclassing values of type ‘Any’ when defining classes.

Default: false

Untyped definitions and calls

--disallow-untyped-calls · boolean

Disallow calling functions without type annotations from functions with type annotations.

Default: false

--untyped-calls-exclude MODULE · string

Disable —disallow-untyped-calls for functions/methods from specific package, module, or class. May be repeated.

--disallow-untyped-defs · boolean

Disallow defining functions without type annotations or with incomplete type annotations.

Default: false

--disallow-incomplete-defs · boolean

Disallow defining functions with incomplete type annotations.

Default: false

--check-untyped-defs · boolean

Type check the interior of functions without type annotations.

Default: false

--disallow-untyped-decorators · boolean

Disallow decorating typed functions with untyped decorators.

Default: false

None and optional handling

--implicit-optional · boolean

Assume arguments with default values of None are Optional.

Default: false

--no-strict-optional · boolean

Disable strict Optional checks.

Default: false (strict Optional enabled)

Configuring warnings

--warn-redundant-casts · boolean

Warn about casting an expression to its inferred type.

Default: false

--warn-unused-ignores · boolean

Warn about unneeded ’# type: ignore’ comments.

Default: false

--no-warn-no-return · boolean

Do not warn about functions that end without returning.

Default: false (warnings enabled)

--warn-return-any · boolean

Warn about returning values of type Any from non-Any typed functions.

Default: false

--warn-unreachable · boolean

Warn about statements or expressions inferred to be unreachable.

Default: false

Strictness flags

--strict · boolean

Strict mode. Enables all strict flags: —warn-unused-configs, —disallow-any-generics, —disallow-subclassing-any, —disallow-untyped-calls, —disallow-untyped-defs, —disallow-incomplete-defs, —check-untyped-defs, —disallow-untyped-decorators, —warn-redundant-casts, —warn-unused-ignores, —warn-return-any, —no-implicit-reexport, —strict-equality, —strict-bytes, —extra-checks.

Default: false

--allow-redefinition · boolean

Allow restricted variable redefinition with a new type.

Default: false

--no-implicit-reexport · boolean

Treat imports as private unless aliased.

Default: false

--strict-equality · boolean

Prohibit equality, identity, and container checks for non-overlapping types.

Default: false

--strict-bytes · boolean

Disable treating bytearray and memoryview as subtypes of bytes.

Default: false

--extra-checks · boolean

Enable additional checks that are technically correct but may be impractical.

Default: false

--disable-error-code NAME · string

Disable a specific error code. May be repeated.

--enable-error-code NAME · string

Enable a specific error code. May be repeated.

Error messages

--show-error-context · boolean

Precede errors with “note:” messages explaining context.

Default: false

--show-column-numbers · boolean

Show column numbers in error messages.

Default: false

--show-error-end · boolean

Show end line/end column numbers in error messages. Implies —show-column-numbers.

Default: false

--hide-error-codes · boolean

Hide error codes in error messages.

Default: false

--show-error-code-links · boolean

Show links to error code documentation.

Default: false

--pretty · boolean

Use visually nicer output: soft word wrap, show source code snippets, and show error location markers.

Default: false

--no-color-output · boolean

Do not colorize error messages.

Default: false (color enabled)

--no-error-summary · boolean

Do not show error stats summary.

Default: false (summary shown)

--show-absolute-path · boolean

Show absolute paths to files.

Default: false

Incremental mode

--no-incremental · boolean

Disable module cache.

Default: false (incremental mode enabled)

--cache-dir DIR · string

Store module cache info in the given folder.

Default: .mypy_cache

--sqlite-cache · boolean

Use a sqlite database to store the cache.

Default: false

--cache-fine-grained · boolean

Include fine-grained dependency information in the cache for the mypy daemon.

Default: false

--skip-version-check · boolean

Allow using cache written by older mypy version.

Default: false

Advanced options

--pdb · boolean

Invoke pdb on fatal error.

Default: false

--show-traceback, --tb · boolean

Show traceback on fatal error.

Default: false

--raise-exceptions · boolean

Raise exception on fatal error.

Default: false

--custom-typing-module MODULE · string

Use a custom typing module.

--custom-typeshed-dir DIR · string

Use the custom typeshed in DIR.

--warn-incomplete-stub · boolean

Warn if missing type annotation in typeshed.

Default: false

--shadow-file SOURCE_FILE SHADOW_FILE · string

When encountering SOURCE_FILE, read and type check the contents of SHADOW_FILE instead.

Report generation

--any-exprs-report DIR · string

Generate a text file report documenting expressions of type Any.

--cobertura-xml-report DIR · string

Generate a Cobertura XML type checking coverage report.

--html-report DIR · string

Generate an HTML type checking coverage report.

--linecount-report DIR · string

Generate a text file report documenting typed and untyped functions and lines.

--linecoverage-report DIR · string

Generate a JSON file mapping each source file to typed line numbers.

--txt-report DIR · string

Generate a text file type checking coverage report.

--xml-report DIR · string

Generate an XML type checking coverage report.

Running code

--explicit-package-bases · boolean

Use current directory and MYPYPATH to determine module names of files passed.

Default: false

--exclude PATTERN · string

Regular expression to match file names, directory names or paths to ignore. May be repeated.

--exclude-gitignore · boolean

Use .gitignore file(s) to exclude files from checking.

Default: false

Miscellaneous

--install-types · boolean

Install detected missing library stub packages using pip.

Default: false

--non-interactive · boolean

Install stubs without asking for confirmation and hide errors (with —install-types).

Default: false

--junit-xml FILE · string

Write a JUnit XML test result document with type checking results to FILE.

--junit-format · string

Specifies JUnit XML format: global (single test with all errors) or per_file (one test per file).

Default: global

--scripts-are-modules · boolean

Script x becomes module x instead of main.

Default: false

Examples

Basic type checking

mypy myprogram.py

Environment variables

MYPYPATH: Additional module search path entries (colon-separated).

MYPY_CACHE_DIR: Override configuration cache_dir path.

Exit codes

• 0: Success, no type errors found
• 1: Type errors found
• 2: Fatal error or mypy encountered an issue