Limit Bazel Disk Cache Size on Mac with Garbage Collection

Bazel supports automatic disk-cache garbage collection through size and age limits. If your shared disk cache repeatedly grows after manual cleanups, setting a retention policy can be more useful than deleting it after every build.

First confirm that the large directory really is the disk cache. Bazel output directories, repository downloads, and a disk cache are different storage categories. A limit for one should not be expected to control all three.

Check the Bazel version and configuration

bazel --version
bazel help build

Look for the supported disk-cache options in the help output, and inspect your user and project .bazelrc files for the configured --disk_cache location. A wrapper or CI script may also pass its own settings. Record the effective directory before changing any policy.

The Bazel cache documentation describes disk-cache garbage collection beginning with Bazel 7.4. Verify support in your installed release because the option names are experimental and older installations may reject them.

Set a deliberate budget

For a release that supports these options, the following .bazelrc example limits the configured disk cache by size and entry age:

build --experimental_disk_cache_gc_max_size=20G
build --experimental_disk_cache_gc_max_age=14d

Twenty gigabytes and fourteen days are illustrative choices, not a universal recommendation. A developer switching frequently between two large branches may benefit from retaining more data than someone building one small project. Choose a budget after observing your normal workflow.

This example assumes you have already configured a disk cache. It does not select or create a cache location for you. Keep machine-specific capacity choices in an appropriate local configuration unless your team intentionally wants a shared policy.

Allow the server to become idle

Bazel documents collection during idle periods, with a default idle delay of five minutes. Completing a build and immediately checking Finder may therefore show no change. A continuously busy server may not collect on your preferred schedule.

Run a normal build, leave the server idle, and compare the same directory afterward. Avoid treating the size limit as a reservation that prevents temporary growth during a build. It is a cleanup policy, so you still need enough working headroom.

Measure the build-time tradeoff

Record build duration and cache size before and after a week of normal use. If everyday builds repeatedly regenerate expensive outputs, increase the budget or relax the age limit. If the directory still consumes too much space, tighten one setting at a time so you can understand the effect.

For example, changing both the cache location and retention limit together makes a slower build ambiguous: was the new drive slower, or did the required result get evicted? Separate those experiments.

If the large directory does not shrink

Check whether a command-line flag overrides your configuration, whether the active Bazel version accepts the options, and whether you measured the correct folder. Then compare the disk cache with the output and repository storage described in our Bazel storage cleanup guide.

Do not respond to a configuration problem by deleting every Bazel-related directory. Preserve project source and record a reproducible build before clearing generated output. For other toolchains on the same Mac, use the developer cache map to avoid assigning the entire storage problem to Bazel.