PRE_COMMIT_HOME: The Hook Environment Cache
pre-commit stores each built hook environment under ~/.cache/pre-commit so it is built once and reused.
Building hook environments is the slow part of pre-commit. Caching the cache directory between CI runs is the single biggest speedup you can make.
What it does
On first use of a hook, pre-commit clones the repo and builds a language environment (virtualenv, node_modules, etc.) under its cache directory, default ~/.cache/pre-commit. Subsequent runs reuse it. PRE_COMMIT_HOME (or XDG_CACHE_HOME) relocates that directory.
Common usage
# default location
ls ~/.cache/pre-commit
# relocate the cache (e.g. to a cached CI path)
export PRE_COMMIT_HOME="$CI_PROJECT_DIR/.cache/pre-commit"
pre-commit run --all-filesVariables
| Variable | What it does |
|---|---|
| PRE_COMMIT_HOME | Override the cache directory location |
| XDG_CACHE_HOME | If set, cache lives under $XDG_CACHE_HOME/pre-commit |
| ~/.cache/pre-commit | Default cache path on Linux |
| pre-commit gc | Remove cached envs for repos no longer referenced |
| pre-commit clean | Delete the entire cache directory |
In CI
Cache the directory pre-commit actually uses. On GitHub Actions that is ~/.cache/pre-commit; on GitLab set PRE_COMMIT_HOME inside the project dir so the runner cache picks it up. Key the cache on the config hash so it invalidates when hook revs change. Run pre-commit gc periodically to keep the cache from growing unbounded.
Common errors in CI
If every run still logs "[INFO] Initializing environment", the cached path does not match PRE_COMMIT_HOME, or the cache key changes every run. A corrupted cache after an interrupted job shows up as odd environment errors; pre-commit clean and rebuild. On read-only HOME, set PRE_COMMIT_HOME to a writable path or the cache build fails with permission denied.