mypy --python-version: Target a Python Version
mypy --python-version checks your code as if it ran on the given Python version, regardless of the interpreter mypy runs under.
You can run mypy on 3.12 but check that the code is valid on 3.9. This flag drives which syntax and typeshed stdlib stubs apply.
What it does
mypy --python-version X.Y selects the language features and the version-specific typeshed standard library stubs mypy uses. It does not change which interpreter mypy itself runs under; it only changes the target it checks against.
Common usage
mypy --python-version 3.9 src/
# config form
# [tool.mypy]
# python_version = "3.9"
# also pin the target OS for platform-specific checks
mypy --python-version 3.9 --platform linux src/Options
| Flag or key | What it does |
|---|---|
| --python-version X.Y | Target language and stdlib version |
| python_version | Config key form (a string like "3.9") |
| --platform <os> | Target sys.platform (linux, darwin, win32) |
| --python-executable | Point at a venv so installed package stubs resolve |
In CI
Set python_version explicitly so results do not drift with the runner image. In a version matrix, vary --python-version per leg to confirm the code is valid on each supported release. Caching is per-target, so .mypy_cache should be keyed by the version to avoid invalidating it across legs.
Common errors in CI
Checking against an older --python-version flags new syntax: "X syntax is only available in Python 3.10+" or match statements on 3.9. Targeting a newer version than you support lets that syntax slip through; pin python_version to your real minimum. A type that exists only in newer typeshed will be "Name not defined" on the older target.