Bazel Remote Execution and Build Caching Explained

Updated on Oct 18, 2026

9 min read

Bazel remote execution helps teams shorten large builds by reusing previous work and running independent build actions on a shared pool of machines. It is especially useful when a repository has many targets, multiple developers repeat the same builds, or continuous-integration workers spend more time compiling and testing than delivering changes. The key idea is not simply to move a build to the cloud: Bazel describes work as a graph of actions, and remote services can cache or execute those actions when their inputs and environment are identified consistently.

This explainer covers how remote execution relates to content-addressed build caching, what the service components do, how to enable them, and why a cache hit is only safe when the action is reproducible.

What Is Bazel Remote Execution?

Bazel is an open-source build and test system. A build definition describes targets and dependencies; Bazel analyzes those definitions, constructs an action graph, and runs only the actions needed for the requested targets. An action might compile a source file, generate code, package an artifact, or run a test.

With remote caching, Bazel checks a shared service for a result before doing work again. With remote execution, Bazel can also send eligible actions to workers on other machines. The Bazel remote execution overview describes how clients and remote workers coordinate this work. These are related but separate capabilities: a team can use a remote cache while executing actions locally, or configure both caching and execution.

The cache is content-addressed: stored files and directory trees are identified by digests of their contents rather than by a mutable filename alone. The Bazel remote caching documentation describes the two central stores: an action cache, which maps action keys to result metadata, and a content-addressable store (CAS), which holds output data. The Remote Execution API definitions specify the service interfaces used to exchange action descriptions, input data, and results.

Why Does It Exist?

In a large codebase, many build actions are repeated across branches, developers, and CI jobs. A local build directory can reuse work on one machine, but that reuse is limited when a developer switches devices or a CI job starts on a clean worker. Running every action again wastes compute and makes build latency depend on the size of the local machine.

Remote caching makes eligible results available to other clients. Remote execution goes further by letting a shared worker pool provide CPU, memory, and platform capacity. A developer can keep using the same Bazel command while the system distributes eligible work behind the client.

Distribution does not make an incorrect build correct. If an action reads an undeclared file, depends on the current time, or silently uses a tool installed on one worker, Bazel may not include that hidden input in the action key. A result can then be reused under conditions that appear identical to the cache but are not. Reliable remote builds therefore depend on explicit inputs, stable toolchains, and controlled execution environments.

How Remote Execution and Caching Work

At a high level, Bazel and the remote service coordinate a lookup, optional execution, and transfer of output data:

Bazel analyzes the requested targets and creates actions with declared inputs, commands, environment settings, and outputs.
For an action, Bazel computes a key from the action description and the digests of its inputs. A change to a declared input or command should produce a different key.
Bazel checks the action cache. On a hit, the service returns metadata describing the result, including output digests. Bazel fetches output bytes from the CAS when it needs them.
On a miss, Bazel either runs the action locally or submits it to a remote executor. The remote worker obtains missing inputs from the CAS, executes the action in its configured environment, and uploads output files and metadata.
The action result is recorded in the action cache so another compatible request can reuse it.

The split between the two stores matters. The action cache answers “what result belongs to this action key?” The CAS answers “where are the bytes for this digest?” A cache entry may refer to many output blobs, and content addressing allows identical blobs to be shared rather than uploaded repeatedly.

Feature	Local build cache	Remote cache	Remote execution
Where actions run	On the Bazel client	On the client after a miss	On remote workers for eligible actions
Reuse scope	Usually one machine or output base	Shared by clients with access	Shared results plus distributed execution
Data exchanged	Local files	Action metadata and output blobs	Inputs, action requests, status, and output blobs
Main benefit	Avoids repeating work on one client	Reuses work across clients and CI jobs	Adds shared compute and execution capacity
Main cost	Local disk and maintenance	Network, service capacity, and storage	Network plus worker scheduling and maintenance
Key risk	Stale local state	Incorrectly shared or incomplete action keys	Non-hermetic actions behave differently across workers

Bazel commonly communicates with remote services through gRPC. The transport’s stream multiplexing and framing are defined by the IETF HTTP/2 specification. This network layer does not define whether an action is safe to cache; that depends on Bazel’s action inputs and the service’s execution policy.

Components and Key Concepts

Action graph. Nodes represent build actions and edges represent dependencies. Bazel can schedule independent nodes concurrently while waiting for prerequisites. Declaring dependencies accurately lets it determine both what needs rebuilding and what data must reach a worker.

Action cache. This is a mapping from an action key to a result, such as exit status and output digests. It is not a general-purpose cache of arbitrary project files. A cache hit means the service has a result for the computed key; it does not prove that every real-world dependency was declared.

Content-addressable store. The CAS stores blobs and tree metadata by digest. Since identical content has the same digest, clients can avoid transferring data already present in the store. This is useful for large artifacts and repeated inputs, but it still requires storage limits, retention policies, and access controls.

Remote executor and workers. The executor accepts requests and coordinates their lifecycle; workers perform actions under configured operating systems, architectures, toolchains, and resource limits. The worker platform must match the action’s declared requirements. A successful result on a Linux worker, for example, cannot automatically stand in for a Windows-specific action.

Remote Execution API (REAPI). REAPI describes service operations for action-cache lookup and update, CAS data transfer, and action execution. A particular service may implement only a subset or add authentication and scheduling behavior. The API contract and the worker’s actual environment both matter when comparing providers.

Real-World Use Cases

Remote caching is useful when CI jobs repeatedly build overlapping targets, when developers switch between machines, or when clean ephemeral runners would otherwise compile the same dependencies for every change. A shared cache can make the first build on a fresh runner cheaper if its actions match results already produced elsewhere.

Remote execution is most useful when a project has many independent, CPU- or memory-intensive actions and a local workstation or CI runner cannot execute them quickly enough. Teams can share a worker pool, choose workers with appropriate resources, and avoid installing every build tool directly on each client.

The gains vary by workload. Small builds may finish before network setup and transfer overhead are worthwhile. A slow cache, a saturated executor, cross-region traffic, or large outputs can erase the benefit. Measure cache hits, bytes transferred, queue time, worker utilization, and end-to-end build duration rather than assuming that more remote work is always faster.

Getting Started with a Remote Cache

Install Bazel or Bazelisk using the official installation guide, then confirm the project builds locally. Bazelisk selects the version declared by the repository, which helps keep local and CI clients aligned.

bazel --version
bazel build //...

After an administrator provisions a compatible remote cache, add its endpoint to .bazelrc. The hostname below is an example, not a public service:

build:remote-cache --remote_cache=grpcs://cache.example.com
build:remote-exec --remote_cache=grpcs://cache.example.com
build:remote-exec --remote_executor=grpcs://executor.example.com

The first configuration enables shared caching while actions still execute locally on a cache miss. The second enables both the cache and a remote executor. Select the configurations explicitly:

bazel build --config=remote-cache //...
bazel build --config=remote-exec //...

Run the same remote-cache build again to test reuse. Inspect the build summary and the cache service’s metrics for action-cache hits, misses, and transferred bytes. Do not use the presence of restored standard output or error as proof that an action ran: Bazel’s remote cache can store those streams with the action result. For a specific target, bazel aquery //path/to:target can help inspect the actions Bazel plans to execute.

Use the protocol and authentication settings required by the selected service. Keep credentials outside checked-in configuration, use encrypted transport when supported, and restrict who can write to a shared cache. A remote execution service should also enforce worker resource limits and isolate actions from one another.

Before broad adoption, compare local and remote results on representative targets. Fix undeclared inputs, pin toolchains, and avoid depending on machine-specific paths, ambient environment variables, network responses, or mutable external files. Treat cache namespaces and permissions as part of the build’s security boundary; never let an untrusted contributor publish results that trusted builds will consume.

Common Misconceptions

“Remote caching and remote execution are the same feature.”

They are distinct. A remote cache can serve results while the client executes cache misses locally. Remote execution delegates eligible cache misses to workers; it usually pairs with caching but does not require the same service to provide both.

“A content hash guarantees a correct result.”

A digest identifies the inputs Bazel knows about. It cannot account for a file, environment variable, network response, or tool version that the action failed to declare. Hermetic actions and complete dependency descriptions are what make cache reuse trustworthy.

“Remote execution always makes builds faster.”

Remote scheduling, network transfer, and output downloads add overhead. Tiny or highly sequential workloads may run faster locally. Use measurements to decide which actions and projects benefit, and retain a safe local fallback for service outages or unsupported targets.

Changelog

Initial publication.

Last updated: Initial publication.