ccache compiler_check: Keep Hits After Compiler Changes
ccache compiler_check decides what about the compiler goes into the cache key, trading safety against hit rate.
By default ccache hashes the compiler binary's size and mtime. In CI those change when a runner reinstalls the same compiler, busting the cache. compiler_check lets you key on content or a version string instead.
What it does
compiler_check controls how ccache fingerprints the compiler. The default mtime uses size and modification time, which is fast but changes when the toolchain is reinstalled. content hashes the binary itself; a command like %compiler% -v keys on the version string, which stays stable across reinstalls of the same version.
Common usage
# key on the compiler's reported version (stable across reinstalls)
export CCACHE_COMPILERCHECK="%compiler% -v"
# or hash the compiler binary contents
export CCACHE_COMPILERCHECK=content
# persist in config instead of the environment
ccache --set-config compiler_check=contentOptions
| Value | What it does |
|---|---|
| mtime (default) | Hash compiler size and mtime (fast, fragile in CI) |
| content | Hash the compiler binary contents |
| %compiler% -v | Run a command and hash its output (version string) |
| string:<value> | Hash a fixed string you control |
| CCACHE_COMPILERCHECK | Environment form of the setting |
In CI
On ephemeral runners that reinstall the toolchain each run, the default mtime check guarantees a cold cache. Switch to %compiler% -v (or content) so a reinstall of the same compiler version still hits. Confirm the change with ccache -s showing hits on the second run.
Common errors in CI
Mysterious 0% hit rate after restoring a warm cache, with everything else correct, is the classic mtime symptom on reinstalled toolchains; set compiler_check to a version command or content. Using content adds a small per-compile hashing cost but is safe; a stale string: value can cause false hits, so only use it when you control the toolchain exactly.