pre-commit clean: Reset the Hook Cache
pre-commit clean removes the entire pre-commit cache directory, forcing every hook environment to rebuild.
When a cached environment is stale or corrupted, clean is the blunt fix. The next run rebuilds everything from scratch.
What it does
pre-commit clean deletes the whole cache directory (default ~/.cache/pre-commit or PRE_COMMIT_HOME). Every hook environment is gone, so the next pre-commit run reinitializes each one, printing "[INFO] Initializing environment" again.
Common usage
pre-commit clean
# clean then rebuild explicitly
pre-commit clean && pre-commit install-hooksclean vs gc
| Command | Effect |
|---|---|
| pre-commit clean | Delete the whole cache; everything rebuilds |
| pre-commit gc | Delete only stale, unreferenced environments |
| rm -rf ~/.cache/pre-commit | Manual equivalent of clean |
In CI
Reach for clean when a cached env is wrong after an additional_dependencies change, or to invalidate a poisoned CI cache. Because it forces a full rebuild, the run after clean is slow and re-downloads everything, so do not run it on every CI invocation; use it only to recover, then let the cache repopulate.
Common errors in CI
clean itself rarely fails, but the run after it logs "[INFO] Initializing environment for ..." for every hook, which is expected, not an error. If a hook kept running an old tool version despite a version bump, clean is the cure: the stale cached environment is removed and rebuilt with the new pin. On a read-only cache mount, clean reports a permission error.