1.1.3 Server/Client Architecture

Every command from 1.1.1 Commands, whether build, test, or run, starts the same way: the bazel process you launch is only a client. It connects to a long-lived Bazel server associated with the workspace's output_base, and that server keeps an analysis cache of loaded BUILD files, the dependency graph, and related metadata in memory across invocations¹. That is why the first command after startup feels cold while the second can feel instantaneous: the expensive loading and analysis work is often already sitting in the server's memory².

One command reaches one long-lived Bazel server

Commands that use the same output_base use the same server

CLIENT

What did you type?

Short-lived front end

bazel build //foo

OUTPUT BASE

Which server handles it?

Maps command to one daemon

bazel info output_base

SERVER

What stays in memory?

Reused by later commands

loaded packages + graph

PERSISTENT STATE

What survives restart?

Valid outputs stay on disk

outputs + action cache

bazel shutdown clears the server's memory. Valid outputs on disk may still be reused after restart.

One command, two processes

The client is short-lived: it parses flags, finds the right server, sends the request, prints output, and exits¹. The server is the long-lived JVM process that does the heavy lifting and stays around in the background for later commands³. Bazel identifies that server by output_base, not by the shell process that launched it⁴.

That detail explains two everyday CLI behaviors. First, bazel build, bazel query, and bazel test can all benefit from the same warm state when they hit the same server¹. Second, bazel info output_base (1.1.7 bazel info) tells you which on-disk tree anchors that server's state⁴.

Why the first build is slow

A cold invocation has to start the server, load and evaluate the relevant BUILD files, and construct the dependency graph in memory². 2.2.1 Loading, Analysis & Execution later separates that work into loading, analysis, and execution. For now, the first command pays the setup cost, then repeated commands amortize it.

This shows up directly in build output. On the first build, Bazel reports packages loaded and targets configured. Repeating the same command immediately afterwards turns into a null build with both counts at zero⁵:

INFO: Analyzed target //foo:foo (14 packages loaded, 48 targets configured).
...
INFO: Analyzed target //foo:foo (0 packages loaded, 0 targets configured).

That speedup comes mostly from the server's in-memory analysis cache². If the server restarts, or if Bazel discards the analysis cache because your options changed, the next build becomes cold again².

Warm server vs persistent outputs

It helps to separate two different things that both make later builds faster.

The warm server keeps the analysis cache alive. 1.1.4 Inspecting Server State focuses on how to inspect that state from the CLI: what lives under output_base, what only lives in memory, and which commands reveal each layer. 2.4.1 Skyframe & Incrementality then explains the mechanism behind that cache. Lose that server, and Bazel has to reconstruct the dependency graph².

The output tree under the output base (see 0.1.4 Output Root) is different. Those files live on disk, so bazel shutdown clears the analysis cache but does not automatically invalidate already-produced outputs⁶. A restarted server may still avoid rerunning actions if the outputs in bazel-out/ are still valid⁶. A "cold build" can therefore redo loading and analysis while reusing valid execution results instead of recompiling everything.

extra

One at a time means one server

The usual rule of thumb is "Bazel only runs one command at a time per workspace," but the precise rule is narrower: one active invocation per server/output base¹. If two commands use the default output base, they contend for the same server lock and one waits, or fails immediately if --noblock_for_lock is set¹^,⁷.

If you intentionally give commands different output bases, Bazel starts different server instances and they can run concurrently⁴:

OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
bazel --output_base ${OUTPUT_BASE}1 build //foo &
bazel --output_base ${OUTPUT_BASE}2 build //bar

Most day-to-day work should use the default behavior. Separate output bases are mainly for scripts, experiments, or workflows that need isolation⁴^,⁷.

Server lifecycle

A Bazel server shuts itself down after being idle for 3 hours by default, though --max_idle_secs can change that¹^,⁴. You can also stop it explicitly with bazel shutdown, which is useful when scripted builds would otherwise leave idle daemons behind¹^,⁷.

Restarts happen for two common reasons. The obvious one is version mismatch: the client sees that the running server does not match the Bazel version it needs and starts a new one¹. The subtler one is a startup-option mismatch. Options such as --output_base or --host_jvm_args apply to the server JVM itself, so if they differ from the running server's startup settings, Bazel restarts the server to get a matching process⁴.

That also explains why --batch is slower. Batch mode skips the normal client/server model, runs a one-shot Java process, and gives up the analysis cache that makes iterative CLI work fast⁴. Likewise, bazel clean --expunge (1.1.6 bazel clean) is deliberately destructive: it removes the whole output base and stops the server³.

key takeaway

When a repeated Bazel command is suddenly slow, think about server state first. Did the command hit the same output_base and reuse the same long-lived server, or did the server restart, time out, or discard its analysis cache? That mental model explains most "first build slow, next build fast" behavior before you ever need to learn Skyframe internals.

Check your understanding · 3 questions

1.Why is the first Bazel command after starting the server slower than subsequent ones?

Select one answer

2.True or false: what does bazel shutdown affect?

Choose True or False for each sentence

bazel shutdown destroys all previously built outputs in bazel-out/.

shutdown drops the in-memory analysis cache but on-disk outputs survive.

shutdown deletes all files under the repository cache.

shutdown removes bazel-out/ and the MODULE.bazel lockfile.

3.Which of the following cause the Bazel server to restart?

Select all that apply

0 of 3 answered

Client/server implementation — Long-lived server, shared cache across commands, one invocation per server, idle timeout, version-based restart ↩¹ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸
Optimize Iteration Speed — Analysis cache lives in the server, cold runs after restart or cache discard, separate output bases create separate servers ↩¹ ↩² ↩³ ↩⁴ ↩⁵
Commands and Options — Bazel server runs in its own JVM, shutdown stops it, and clean --expunge removes the output base ↩¹ ↩²
Commands and Options — --output_base, startup-option restarts, --batch, --max_idle_secs, and concurrent servers via different output bases ↩¹ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷
Build programs with Bazel — Null build example showing repeated command with 0 packages loaded, 0 targets configured ↩
The Many Caches of Bazel — Distinction between in-memory Skyframe state and persistent output tree cache that survives bazel shutdown ↩¹ ↩²
Calling Bazel from scripts — Output-base lock, scripted server cleanup, and --noblock_for_lock behavior ↩¹ ↩² ↩³

← Previousbazel run & Runfiles Next →Inspecting Server State