mypy

Type check a specific file

$ mypy [path/to/file.py]

$ mypy [[-m|--module]] [module_name]

$ mypy [[-p|--package]] [package_name]

$ mypy [[-c|--command]] "[code]"

$ mypy --ignore-missing-imports [path/to/file_or_directory]

$ mypy [[--tb|--show-traceback]] [path/to/file_or_directory]

$ mypy --config-file [path/to/config_file]

$ mypy [[-h|--help]]

mypy [options] [files/directories ...]
mypy --module <module_name>
mypy --package <package_name>
mypy --command <command_string>

--help, -h
    Show program's help message and exit.

--version, -v
    Show program's version number and exit.

--strict
    Enable all strict type checking flags. This is equivalent to enabling a large set of individual strictness checks, promoting higher code quality.

--ignore-missing-imports
    Suppress errors about imports that cannot be resolved. Useful for libraries without type stubs or when external dependencies are not fully typed.

--disallow-untyped-defs
    Report an error for any function that has no type annotations.

--no-implicit-optional
    Generate an error for arguments with a default value of None in a function if the type annotation is not Optional.

--warn-unused-ignores
    Report an error if a # type: ignore comment is unnecessary.

--warn-return-any
    Warn whenever an explicit Any type is returned.

--config-file <PATH>
    Read configuration from the specified file. Defaults to mypy.ini, setup.cfg, or pyproject.toml in the current directory or parent directories.

--pretty
    Use nicer error messages, such as colored output (if supported by terminal) and showing source code snippets.

--show-column-numbers
    Show column numbers in error messages.

--python-version <X.Y>
    Use the specified Python version for checking (e.g., 3.8).

--install-types
    Install missing type stubs for imported modules interactively.

--exclude <PATTERN>
    Exclude files or directories matching the given regular expression pattern.

--namespace-packages
    Enable support for PEP 420 namespace packages.

--incremental
    Enable incremental checking (default). mypy will only re-check files that have changed, or files that depend on them.

--no-incremental
    Disable incremental checking, forcing a full re-check.

--cache-dir <DIR>
    Store and retrieve incremental build cache data from the specified directory.

--follow-imports <MODE>
    How to follow imports: normal (default), silent, skip, error.

--warn-no-return
    Warn if a function is not annotated as returning None but does not explicitly return a value.

mypy is a static type checker for Python. It checks your Python code against type hints (introduced in PEP 484) to find common programming errors before your code ever runs. By analyzing your program's type annotations, mypy can catch issues like incorrect argument types, missing attributes, or incompatible assignments, significantly improving code reliability and maintainability. It helps developers write more robust and self-documenting code, especially in large codebases, by ensuring that functions are called with the expected types and variables are used consistently. mypy acts as a valuable development tool that complements unit testing and runtime checks, providing an early warning system for potential type-related bugs.

mypy can be slow on large codebases without proper caching or incremental builds. It requires type hints, which adds verbosity to code but improves clarity. It does not catch runtime errors or logic errors. Not all third-party libraries provide type stubs, potentially leading to the need for --ignore-missing-imports or the use of Any types.

mypy relies heavily on type hints, which are annotations in Python code that indicate the expected types of variables, function arguments, and return values. PEP 484 formalized these hints, making them a standard part of Python syntax.

mypy's behavior can be extensively configured using files like mypy.ini, setup.cfg, or pyproject.toml. These files allow users to set global options, per-module options, and define custom error codes, providing fine-grained control over the type checking process.

Many modern Integrated Development Environments (IDEs) and text editors (e.g., VS Code, PyCharm, Sublime Text) have built-in support or plugins for mypy, providing real-time type checking feedback as you write code, enhancing the development experience.

mypy was initially developed by Jukka Lehtosalo at Dropbox in 2013, predating the official introduction of type hints in Python 3.5 (PEP 484) in 2015. It served as a proof of concept and a driving force behind the standardization of type hints in Python. Since then, mypy has become the reference implementation for static type checking in Python and is actively maintained and developed by the Python community, with contributions from various companies and individual developers. Its adoption has grown significantly, especially in large-scale Python projects, due to its ability to improve code quality and maintainability.

python(1), flake8(1), pylint(1), black(1)