mypy in pyproject.toml: The [tool.mypy] Table
mypy reads configuration from the [tool.mypy] table in pyproject.toml.
Putting mypy settings in pyproject.toml keeps one config file for the project. The keys are the same as the CLI flags with underscores.
What it does
mypy looks for a [tool.mypy] table in pyproject.toml (it requires the tomli/tomllib parser, bundled with modern mypy). Each key mirrors a CLI flag with dashes replaced by underscores, for example strict, python_version, and warn_unused_ignores.
Common usage
[tool.mypy]
python_version = "3.11"
strict = true
warn_unused_ignores = true
exclude = ["^build/", "^tests/fixtures/"]
[[tool.mypy.overrides]]
module = "legacy.*"
disallow_untyped_defs = falseOptions
| Key | What it does |
|---|---|
| [tool.mypy] | Global settings table |
| [[tool.mypy.overrides]] | Per-module override blocks (an array of tables) |
| module | Glob of modules the override applies to |
| strict / warn_unused_ignores | Boolean settings (lowercase true/false) |
| files | Default paths to check when none are given |
In CI
Booleans in TOML are lowercase true/false, not Python True/False; the latter is a parse error. The overrides table uses double-bracket [[...]] array-of-tables syntax. Cache .mypy_cache between runs and the config-driven check stays fast.
Common errors in CI
"Cannot parse config file" usually means a TOML syntax slip: True/False instead of true/false, or single brackets where the overrides array needs [[tool.mypy.overrides]]. If mypy seems to ignore the file, an older mypy without a TOML parser will not read pyproject.toml; upgrade mypy or use mypy.ini.