sccache starts paying off when cache misses become evidence

The Parallel Computer Center at Sweden's Royal Institute of Technology in 2010. A shared compiler cache is ultimately a physical service: compute, storage, network paths, and failure policy behind every apparent shortcut. Photograph by Johan Fredriksson.[11]

Adding sccache to a build takes one line. Migrating to it takes evidence. The useful change is not the wrapper itself; it is the move from compilation work trapped on one runner to artifacts that another compatible runner can safely reuse. That move pays when many jobs repeat expensive Rust or C/C++ compilation under stable inputs. It disappoints when toolchains churn, paths differ, most work is uncacheable, or a remote lookup costs more than the compilation it replaces.

The migration should therefore begin with misses. A miss report reveals whether the build has enough repeated, cacheable work to justify shared infrastructure. It also prevents a familiar CI mistake: adding a bucket, credentials, and another network dependency before proving that local caching helps.

This is a timely boundary to test. sccache 0.16.0, released on June 19, 2026, stabilizes the multi-level caching work introduced in 0.15.0 and allows every storage backend to be marked read-only.[7] Those features make a sensible progression possible: local proof first, a shared backend second, and a fast local tier in front only when the measurements support it.

Image context: the cover shows a real machine room at the Royal Institute of Technology's Parallel Computer Center, not an abstract cloud. It fits this migration because a “shared cache” is a claim on actual storage, network, and operational capacity. The point is to shorten compilation without making that hidden service harder to reason about.[11]

Start with the smallest reversible change

For Rust, the first experiment is RUSTC_WRAPPER=sccache; Cargo also accepts build.rustc-wrapper in its configuration. For C and C++, CMake can set CMAKE_C_COMPILER_LAUNCHER and CMAKE_CXX_COMPILER_LAUNCHER to sccache. With no remote backend configured, the tool uses local disk, starts a local server when needed, and exposes counters through sccache --show-stats.[1] The local cache defaults to 10 GB.[4]

That local-only phase matters because it separates two questions:

Can this workload reuse compiler outputs? Run one cold build, a second build at the same commit after deleting ordinary build outputs, and a third after a representative source change. Record wall time, compile requests, cache hits, misses, non-cacheable calls, and cache errors.
Can another runner reuse them economically? That is a later network and storage test. Do not use remote-cache results to hide a poor local hit pattern.

Firefox's own build documentation states the tradeoff plainly: the initial build with sccache is slower because the tool must process files and storage, while later compatible builds can benefit.[10] A team should expect the same shape without borrowing Mozilla's outcome. Its gate is workload-specific: retained CI minutes must exceed hashing, preprocessing, transfer, storage, and operational cost across a representative week.

This is also why restoring an entire Cargo target directory and using sccache are not interchangeable. Cargo describes sccache as a third-party shared cache that can reuse built dependencies across workspaces.[8] A restored target tree preserves one build directory's broader state; sccache answers narrower compiler invocations by content-derived keys. The latter is more portable, but it cannot replace every artifact that the former carries.

A cache hit is a statement about build identity

sccache does not key a result only by source filename. For Rust, its documented hash inputs include the source digest, the rustc executable path, host triple, sysroot, shared libraries in the sysroot, and parsed compiler arguments. For C and C++, the key includes the preprocessed source, compiler binary, language, architecture and dependency arguments, relevant environment variables, and other compilation details.[2]

That breadth is the safety mechanism. It is also the main source of misses. Two runners that look equivalent to an operator may present different checkout paths, compiler builds, sysroots, feature flags, target triples, SDKs, or environment values to the cache.

Path identity deserves an explicit migration task. Absolute paths must match by default. SCCACHE_BASEDIRS can strip one or more absolute prefixes before key computation so /work/job-184/project and /work/job-927/project do not miss merely because an executor chose a different directory. The longest matching prefix wins, and matching is case-sensitive outside Windows.[1] Normalize only roots that are genuinely equivalent; erasing a meaningful path distinction can make the cache harder to audit.

Then define intentional separation. SCCACHE_S3_KEY_PREFIX can scope objects inside a bucket, while SCCACHE_C_CUSTOM_CACHE_BUSTER can force C-family invocations into a new key space when an external compatibility boundary is not already represented.[1][6] Useful divisions may include operating system, architecture, toolchain channel, release versus sanitizer builds, or a deliberate epoch after a suspected bad artifact. Avoid putting the commit SHA in every prefix: that recreates runner-local isolation and defeats cross-commit reuse.

Inventory what will never hit

A rising miss count is not automatically a broken cache. Some compiler work is deliberately outside the model.

Rust incremental compilation must be disabled for a crate to be cached. Crates that invoke the system linker—including binaries, dynamic libraries, procedural macros, and related outputs—cannot be cached by sccache; procedural macros that read undeclared files may also be problematic.[3] The project README separately notes that Cargo enables incremental compilation for workspace members and path dependencies in the debug profile by default.[1] A CI experiment should record its CARGO_INCREMENTAL and profile settings rather than comparing a developer's incremental build with a clean release job as if they were the same workload.

C and C++ have a different edge. The local backend can cache preprocessor output, but that fast path is limited to local storage and is disabled by several compiler options and time-dependent macros. The documentation also calls out conditions under which an aggressively configured preprocessor cache could return stale output.[4] Remote hits may still save compilation, but a miss can retain meaningful preprocessing cost. C++20 module support is partial: current documentation covers some Clang named-module flags, while GCC and MSVC module invocations bypass the cache.[1]

Before adding shared storage, classify the top miss and non-cacheable reasons by language, target, and job. If most expensive work lands in link steps, incremental workspace crates, unsupported modules, or one-off generated code, a larger cache will store more objects without changing the critical path.

Promote the cache only when runners have something to share

A single long-lived builder may need nothing beyond the 10 GB local default and an eviction policy. A fleet of ephemeral runners is the stronger shared-cache case: one job pays to compile an unchanged dependency, and later jobs on compatible toolchains retrieve the individual object instead of rebuilding it.

The Rust compiler project's CI is a useful independent example, not a transferable benchmark. Its development guide says CI stores persistent sccache artifacts in an S3 bucket and reuses individual LLVM translation units when the source and C/C++ compiler match.[9] LLVM offers large, repeated compilation units across many jobs. A small application with short-lived dependencies and frequent feature changes may see a much weaker return.

Choose the backend by access pattern. GitHub Actions cache is convenient inside that service's workflow scope. Redis or Memcached can suit a low-latency private runner network. S3-compatible storage offers a broad, durable object namespace but adds network distance, lifecycle rules, and credentials.[1][6] The engineering question is not “which backend is supported?” but “which jobs can reach it quickly, which identities may write, and who owns retention and availability?”

Version 0.16.0 also makes a local-plus-remote topology practical. A chain such as disk,s3 checks the faster tier first, falls through on a miss, and backfills faster levels after a slower-level hit. SCCACHE_MULTILEVEL_WRITE_ERROR_POLICY decides whether write failures are ignored, fail only at the first level (l0, the default), or fail at every read-write level (all).[5] The order and policy are production semantics, not tuning garnish. Putting a distant object store first adds that latency to every lookup; choosing all can turn an optional accelerator into a build availability dependency.

Make trust asymmetric

Shared compiler artifacts eventually become linked program code. That makes write access more sensitive than read access. This is an engineering inference from the artifact path, but the operational response is straightforward: trusted branch and release jobs may populate a cache; untrusted fork and pull-request jobs should normally receive read-only access or no remote access at all.

The S3 backend supports READ_ONLY through SCCACHE_S3_RW_MODE. For a public read-only bucket, SCCACHE_S3_NO_CREDENTIALS=true avoids distributing write credentials, and a key prefix can isolate the cache from unrelated objects.[6] Version 0.16.0 extends the read-only capability across all backends.[7] Private caches can apply the same pattern with narrowly scoped read credentials.

Read-only consumers are not a complete trust design. Operators still need bucket policy, encryption in transit, audit logs, retention, and a controlled writer population. They also need a purge path. SCCACHE_RECACHE overwrites cached results for new requests, while a new prefix or cache-buster epoch can quarantine an old namespace.[1] Write authority should be treated like package-registry or artifact-store authority, not like harmless CI scratch space.

Decide whether cache failure may fail the build

The wrapper's default behavior is strict about communication with its local server: an I/O failure fails the build. SCCACHE_IGNORE_SERVER_IO_ERROR=1 instead falls back to the compiler.[1] Multi-level storage has its own write-error policy.[5] These controls answer different failure paths, but they should express one service decision.

For most teams adopting a cache as an accelerator, a cache outage should make builds slower, not red. That favors compiler fallback, an ignore or carefully tested l0 multi-level policy, visible error logging through SCCACHE_ERROR_LOG, and alerts on error rate rather than job failure. A stricter policy can be valid when cache population itself is a tested deliverable, but it should be chosen explicitly.

Rollback must remain boring: unset the compiler wrapper, remove the remote configuration, and run the same build with the real compiler. If that path is untested, the team has accidentally turned a performance tool into infrastructure required for correctness.

A migration sequence that earns its next step

Pin a prebuilt release. The project recommends prebuilt binaries for CI because compiling sccache from source is itself resource-intensive.[1] Record the version beside the toolchain image.
Measure locally. Use the same runner class and three build cohorts—cold, same-revision reuse, and a normal edit. Save both wall time and --show-stats output.
Stabilize identity. Normalize equivalent checkout roots, pin compilers and SDKs, document incremental settings, and separate genuinely incompatible targets.
Add one shared backend for trusted jobs. Track hit rate, bytes transferred, storage growth, cache errors, and end-to-end CI time. A higher hit percentage with slower jobs is a failed experiment.
Open reads carefully. Give untrusted jobs read-only access only after the cache's writer and purge model is clear.
Add multiple levels only for a measured latency problem. A local hot tier is useful when runners persist long enough to reuse it; otherwise it is another directory to provision and inspect.

The migration succeeds when a new compatible runner can skip expensive compilation, cache failure degrades to a known slower path, and operators can explain every major miss. That last condition matters most. Hits save time; misses show whether the system still describes reality.

cronfeed.work