mypy --cache-dir: Speed Up Runs with .mypy_cache
mypy --cache-dir chooses the directory for mypy incremental cache, which defaults to .mypy_cache.
mypy is incremental: it reuses prior analysis from a cache. Persisting that cache between CI runs is the single biggest mypy speedup available.
What it does
mypy stores per-module analysis in a cache directory (.mypy_cache by default) so unchanged files are not re-analyzed. --cache-dir relocates it; --no-incremental disables caching entirely for a clean, slower run.
Common usage
mypy --cache-dir .mypy_cache src/
# pin a location for the CI cache step
mypy --cache-dir "$RUNNER_TEMP/mypy_cache" src/
# force a full re-check (ignores the cache)
mypy --no-incremental src/Options
| Flag | What it does |
|---|---|
| --cache-dir <path> | Directory for the incremental cache (default .mypy_cache) |
| --no-incremental | Disable the cache; analyze everything fresh |
| --sqlite-cache | Store the cache in a single SQLite file |
| MYPY_CACHE_DIR | Environment variable equivalent of --cache-dir |
In CI
Cache .mypy_cache in your pipeline keyed by the mypy version, the Python target, and a lockfile hash, since the cache is invalidated when any of those change. The --sqlite-cache option packs the cache into one file, which can upload and restore faster than thousands of small files on some CI cache backends.
Common errors in CI
A cache restored from a different mypy version or --python-version is simply ignored, so a stale key just removes the speedup rather than causing wrong results. If results look wrong after a cache hit, run once with --no-incremental to rule the cache out, then fix the cache key to include the version.