ruff cache: Speed Up Repeated Runs in CI

Ruff stores per-file results in .ruff_cache so a second run only re-lints files that changed.

Ruff is already fast, but caching makes repeat runs near-instant. On CI you can persist the cache between jobs to skip unchanged files.

What it does

Ruff writes a cache (default .ruff_cache in the project root) keyed on file content and settings. On the next run, unchanged files with the same configuration are skipped. --cache-dir or RUFF_CACHE_DIR relocates it; --no-cache disables it; the cache is invalidated automatically when the Ruff version or config changes.

Common usage

Terminal

ruff check .                          # populates .ruff_cache
ruff check --cache-dir .ruff_cache .  # explicit cache dir
ruff check --no-cache .               # disable caching
RUFF_CACHE_DIR=/tmp/ruff ruff check . # via env

Flags

Flag / env	What it does
--cache-dir <dir>	Where to store the cache
RUFF_CACHE_DIR	Environment variable for the cache dir
--no-cache	Do not read or write the cache
.ruff_cache	Default cache directory
auto-invalidation	Cache is keyed on Ruff version and settings

In CI

Cache .ruff_cache between runs with actions/cache to skip unchanged files, but key the cache on the Ruff version and config hash so a bump does not reuse stale entries. Add .ruff_cache to .gitignore so it is never committed.

Common errors in CI

Stale results almost never happen because Ruff invalidates the cache on version or settings changes, but a misconfigured actions/cache key that ignores the Ruff version can restore a cache from the wrong version; include the version in the key. A read-only or full filesystem makes cache writes fail; use --no-cache or point RUFF_CACHE_DIR at a writable path like /tmp.