mypy.ini and setup.cfg: The INI Config Format
mypy reads INI-style configuration from mypy.ini, setup.cfg, or a path given with --config-file.
The INI format predates the pyproject.toml support and is still widely used. Per-module settings live in their own sections.
What it does
mypy reads a [mypy] section for global options and [mypy-<module>] sections for per-module overrides from mypy.ini (or setup.cfg, or a file named with --config-file). The module name in a section header may use a glob, for example [mypy-legacy.*].
Common usage
[mypy]
python_version = 3.11
strict = True
warn_unused_ignores = True
[mypy-legacy.*]
disallow_untyped_defs = False
[mypy-thirdparty.*]
ignore_missing_imports = TrueOptions
| Section or key | What it does |
|---|---|
| [mypy] | Global options section |
| [mypy-<glob>] | Per-module override section |
| --config-file <path> | Point mypy at a specific config file |
| ignore_missing_imports | Per-module key to mute unresolved imports |
In CI
mypy searches mypy.ini, then setup.cfg, then pyproject.toml in the current directory unless you pass --config-file. Booleans here are capitalized True/False (unlike TOML). Pin --config-file in CI so a stray config in a parent directory is not picked up.
Common errors in CI
"Cannot find config file" appears when --config-file points at a missing path. Settings silently not applying often means the wrong file won precedence; use --config-file to be explicit. Mixing TOML lowercase booleans into an INI file (or vice versa) is a common copy-paste error.