Caching pre-commit Environments on a Named Volume

The pre-commit framework builds an isolated environment per hook, and rebuilding those on every container is slow. This page caches pre-commit's environment directory on a named volume, so hook environments persist across rebuilds and commits stay fast.

Prerequisites

You need a pre-commit-based devcontainer.

  • The pre-commit framework installed and wired in postCreate.
  • A pinned .pre-commit-config.yaml.
  • A named volume for the pre-commit cache.

Cache prerequisitesYou need the cache dir, a volume, a warm step, and a reuse check.Cache dir~/.cache/pre-commitVolumemount itinstall--install-hookswarm itVerifyreuse

Step-by-Step Implementation

  1. Mount the pre-commit cache on a volume.
{
  "mounts": ["source=devcontainer-precommit,target=/home/vscode/.cache/pre-commit,type=volume"],
  "remoteUser": "vscode"
}
  1. Install hooks (and their envs) on create.
{ "postCreateCommand": "pip install pre-commit && pre-commit install --install-hooks" }
  1. Confirm the cache is used.
pre-commit run --all-files   # reuses cached hook environments
  1. Verify a rebuild doesn't rebuild hook envs.

pre-commit cache anatomyCaching the per-hook environment directory on a volume keeps commits fast across rebuilds.Hook envsone per hook, isolatedCache dir~/.cache/pre-commitNamed volumesurvives rebuildsResultfast commits

Common Pitfalls

Slow commits come from rebuilding hook environments each container.

Cache triageA triage path from rebuilding hook envs to a warm, cached pre-commit.Do hook envs rebuild each container?YESCache the dir on a volumeCan the user write the cache?YESHooks pinned + warmedFast, cached hooks

SymptomRoot CauseRemediation
Hook envs rebuild each containerCache dir not on a volumeMount ~/.cache/pre-commit on a volume
Permission denied writing cacheVolume owned by rootchown the cache dir to the user
Cache present but ignoredWrong cache pathTarget the exact pre-commit cache dir
Commits still slowHooks run on all filesRely on staged-file runs

Conclusion

pre-commit's per-hook environments are the slow part; cache them on a named volume and they persist across rebuilds. Warm them in postCreateCommand, and commits stay fast enough that developers never reach for --no-verify.

Cache and keep fastCaching hook environments plus staged-file runs keeps commits fast.Cache~/.cache/pre-commitOn a named volumeWarmed on createKeep fastStaged-file runsPinned hooksHeavy checks in CI

FAQ

What exactly is pre-commit caching? The pre-commit framework creates an isolated environment per hook (a Python venv, a Node install, etc.) under ~/.cache/pre-commit. Caching that directory on a named volume means those environments persist across container rebuilds instead of being rebuilt each time.

Why do my commits get slow after a rebuild? Because a fresh container has no hook environments, so the first run rebuilds them all. Mount the cache directory on a volume and warm it in postCreateCommand, and rebuilds reuse the environments, keeping commit time low.

Does caching affect which checks run? No — the cache only holds the hook environments, not results. Your pinned .pre-commit-config.yaml still determines which hooks run and on which files. Caching purely removes the environment-build cost, so behaviour is unchanged.