Bazel Knowledge Hub

2.4.2 Where Bazel Caches Things

Bazel does not have one cache. It has several layers with different scope and lifetime, and that distinction explains why bazel shutdown hurts loading and analysis but may still leave action outputs reusable, why bazel clean fixes one workspace without deleting shared downloads, and why --disk_cache or a remote cache help across checkouts or machines.1,2,3,4

A result was reused — which state or cache boundary did it cross?
These stores keep different data and have different reuse scopes
Server memory — evaluation state, not an artifact cache
SKYFRAME
Keeps the dependency graph and analysis results in RAM
Reused by the same running server

Cleared by bazel shutdown

Local storage — three separate purposes
REPOSITORY CACHE
Downloaded dependency archives
Shared by workspaces on one machine
repository_cache
OUTPUT BASE
Build products and action metadata
Reused by the same output base
bazel-out · action_cache/
DISK CACHE
A local store using the remote-cache format
Shared across output bases on one machine
--disk_cache · ac/ · cas/
Shared service — action results across machines
REMOTE CACHE
AC maps an action key to result metadata. CAS stores files by content digest.
Reused across developer machines and CI
AC: Action Cache · CAS: Content-Addressable Storage
“Cached” can mean reused evaluation state, downloads, or action results. Name the store before diagnosing a hit or miss.

The five layers

Read the layers from most local and easiest to lose to most shared and durable.1

  1. <a class="cross-ref" href="/book/2~4~1" title="2.4.1 Skyframe &amp; Incrementality"><span class="cross-ref-id">2.4.1</span> Skyframe &amp; Incrementality</a> is the in-memory layer in the long-lived Bazel server. It caches build-state computations such as glob() results, analyzed action graphs, and other metadata, then disappears when that server exits or restarts.1,4
  2. The repository cache stores downloaded archives for external dependencies. It is shared across workspaces on the same machine, you can inspect its location with bazel info repository_cache, and Bazel does not prune it automatically.1,5
  3. The output tree is the workspace-local persistent layer inside output_base. Actual build outputs live under $(bazel info execution_root)/bazel-out/..., while output_base/action_cache/ stores the metadata Bazel uses to decide whether those on-disk outputs are still valid.1,2
  4. --disk_cache=/path turns a local directory into a remote-cache-shaped store with ac/ and cas/ subdirectories. This is useful when you want reuse across branches or sibling checkouts on one machine without running a cache service.1,3
  5. A remote cache is the team-shared version of that idea: an Action Cache plus a CAS on a server. The setup and protocol details belong to 6.2 Shared Remote Cache, but the key contrast here is scope: the output tree is local to one output base, while remote cache entries can be reused across machines.1,3

Inside the output base

For local builds, output_base is the important anchor directory. Under it, Bazel keeps server files, the external/ directory for fetched repositories, action_cache/, and the bazel-out tree under the current execution root.2

That layout also explains bazel clean: it clears the on-disk action cache and removes the workspace's execroot tree, but it does not wipe the separate repository cache.2,5

recommended

When you need the real paths, ask Bazel instead of guessing:

bazel info output_base
bazel info repository_cache
bazel info execution_root
bazel info output_path
bazel info bazel-bin

The convenience symlinks in the workspace, such as bazel-out, bazel-bin, and bazel-testlogs, are only shortcuts into the current output tree.2 The configuration segment inside bazel-out/... changes with the active build configuration, which is why Bazel can keep multiple variants side by side. That becomes concrete in 3.3 Configurable Builds & Platform Basics.2

Common mix-ups

The repository cache and external/ are not the same thing. The repository cache stores downloaded source archives once per machine, while output_base/external/ is where this workspace materializes the repositories it actually uses. A repository-cache hit can skip the download and still leave Bazel with extraction or repo-materialization work inside the current output base.1,2,5

The output tree and disk cache are also easy to conflate. The output tree makes repeated builds in the same workspace fast. The disk cache gives those action results a longer memory across output bases. The next question is not "where are the bytes?" but "what makes two actions count as the same one?" That is the job of 2.4.3 What Makes a Cache Hit.1,3

key takeaway

When a build is "fast because of cache", ask which layer helped. Warm-server speed points to Skyframe, repeated local builds point to the output tree, repeated dependency downloads point to the repository cache, and cross-checkout or cross-machine reuse points to disk or remote cache.1,2,3,4

Check your understanding · 3 questions

1.Match each cache layer to the scenario where it explains a fast build:

Drag each answer onto the matching prompt, or click an answer and then click a prompt

Answers
Skyframe (in-memory)
Output tree / action_cache
Disk cache (--disk_cache)

2.A repeated build is fast in the same checkout, but a fresh checkout on the same machine still has to rebuild local outputs while external archives download quickly. Which layers explain that split?

Select one answer

3.True or false: understanding Bazel cache distinctions.

Choose True or False for each sentence

The repository cache and output_base/external/ serve the same purpose and contain the same files.
The output tree and disk cache both store action results, but the disk cache survives across different output bases.
0 of 3 answered

Footnotes

  1. The Many Caches of Bazel — five-layer cache taxonomy and distinctions between Skyframe, repository cache, output tree, disk cache, and remote AC/CAS ↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10

  2. Output Directory Layout — output_base, execroot, bazel-out, action_cache, convenience symlinks, and bazel clean scope ↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  3. Remote Caching — remote Action Cache plus CAS model and --disk_cache as a local cache in the same format ↩1 ↩2 ↩3 ↩4 ↩5

  4. Client/server implementation — long-lived server reuse and what is lost when the server exits ↩1 ↩2 ↩3

  5. Build programs with Bazel — repository cache location, sharing, SHA256-based reuse, and lack of automatic cleanup ↩1 ↩2 ↩3

← PreviousSkyframe & IncrementalityNext →What Makes a Cache Hit