Where Does Ruff Store Cache and Config?
Ruff caches lint and format results per project and discovers config by walking up the directory tree. Defaults are project local with env var overrides.
Last updated
By default cache goes in .ruff_cache in the project root (the directory with pyproject.toml, ruff.toml, or .ruff.toml). The cache includes a versioned subdirectory and CACHEDIR.TAG plus .gitignore.
Config discovery checks .ruff.toml, then ruff.toml, then pyproject.toml with a [tool.ruff] section in each directory from the target file up to the root. If no project config is found, Ruff falls back to a user config under the OS config directory.
Where Ruff stores this, by platform
.ruff_cache
Project root default (example: C:\Users\<user>\project\.ruff_cache). Override with --cache-dir, RUFF_CACHE_DIR, or cache-dir in config file. Disable reads with --no-cache or RUFF_NO_CACHE=1.
%APPDATA%\ruff\pyproject.toml
User fallback config via etcetera base strategy when no project config exists. Explicit --config path beats hierarchical discovery, and relative paths in --config files resolve from current working directory.
.ruff_cache
Same project local default as Windows and Linux. Precedence for same directory is .ruff.toml over ruff.toml over pyproject.toml. Use extend to inherit from a parent config.
~/Library/Application Support/ruff/pyproject.toml
User fallback config on macOS. Accepted names are .ruff.toml, ruff.toml, or pyproject.toml inside the ruff folder.
.ruff_cache
Same project local default. Cache key includes file mtime, settings hash, and package root. Deleting .ruff_cache is safe and forces full recheck.
~/.config/ruff/pyproject.toml
User fallback config (full form $XDG_CONFIG_HOME/ruff/pyproject.toml). Same three filename options as macOS. Hierarchical discovery ignores pyproject.toml files without a [tool.ruff] section.
Frequently asked questions
How do I set a shared Ruff cache?
Set RUFF_CACHE_DIR=/path/to/cache or add cache-dir = "/path/to/cache" to pyproject.toml under tool.ruff. Config file cache-dir beats RUFF_CACHE_DIR, and --cache-dir beats both.
Which config file wins in one folder?
.ruff.toml wins over ruff.toml, which wins over pyproject.toml. Across directories, the closest config to the checked file wins with no implicit merging unless extend is used.
Notice an outdated path? Let us know.