Bazel Options

Bazel has a tremendously large number of options. Many are obscure, and many are important to use. Some are both obscure and important!

Bazel options may be stored in *.bazelrc files, in several places on disk. The full documentation is at https://bazel.build/run/bazelrc.

We suggest you add to your .bazelrc file as early in your project as possible. Some of these flags may interact badly with some developer behavior or infrastructure setup. In an existing project, it may be wise to add one at a time and wait for "the dust to settle".

Using Aspect bazelrc presets in your project

The .bazelrc file can get large, fast. Some settings don't apply everywhere - some options are appropriate only on CI, and some vary depending on the version of Bazel you use or languages used.

Bazel rc files can contain import statements, which allow you to organize the content better.

To use these presets in your project, simply vendor the *.bazelrc files from https://github.com/bazel-contrib/bazel-lib/tree/main/.aspect/bazelrc into the .aspect/bazelrc folder in your repository and import them in your .bazelrc file.

For example,

.bazelrc

# Import Aspect bazelrc presets
import %workspace%/.aspect/bazelrc/bazel6.bazelrc
import %workspace%/.aspect/bazelrc/bazel7.bazelrc
import %workspace%/.aspect/bazelrc/convenience.bazelrc
import %workspace%/.aspect/bazelrc/correctness.bazelrc
import %workspace%/.aspect/bazelrc/debug.bazelrc
import %workspace%/.aspect/bazelrc/java.bazelrc
import %workspace%/.aspect/bazelrc/javascript.bazelrc
import %workspace%/.aspect/bazelrc/performance.bazelrc

### YOUR PROJECT SPECIFIC OPTIONS GO HERE ###

# Load any settings & overrides specific to the current user from `.aspect/bazelrc/user.bazelrc`.
# This file should appear in `.gitignore` so that settings are not shared with team members. This
# should be last statement in this config so the user configuration is able to overwrite flags from
# this file. See https://bazel.build/configure/best-practices#bazelrc-file.
try-import %workspace%/.aspect/bazelrc/user.bazelrc

Automatic updates

A convenient way to automatically keep your vendored copy up-to-date is to use the write_aspect_bazelrc_presets rule in .aspect/bazelrc/BUILD.bazel:

.aspect/bazelrc/BUILD.bazel

"Aspect bazelrc presets; see https://docs.aspect.build/guides/bazelrc"

load("@aspect_bazel_lib//lib:bazelrc_presets.bzl", "write_aspect_bazelrc_presets")

write_aspect_bazelrc_presets(name = "update_aspect_bazelrc_presets")

When @aspect_bazel_lib is upgraded in your WORKSPACE.bazel or your MODULE.bazel file, a diff_test stamped out by write_aspect_bazelrc_presets will fail if your vendored copy is out-of-date and print the Bazel command to run to update it. For example, bazel run //.aspect/bazelrc:update_aspect_bazelrc_presets.

See the bazelrc example in our bazel-examples repository for a working example.

Correctness options

These are always a good idea to prevent unpleasant surprises.

correctness.bazelrc

# Do not upload locally executed action results to the remote cache.
# This should be the default for local builds so local builds cannot poison the remote cache.
# It should be flipped to `--remote_upload_local_results` on CI
# by using `--bazelrc=.aspect/bazelrc/ci.bazelrc`.
# Docs: https://bazel.build/reference/command-line-reference#flag--remote_upload_local_results
build --noremote_upload_local_results

# Don't allow network access for build actions in the sandbox.
# Ensures that you don't accidentally make non-hermetic actions/tests which depend on remote
# services.
# Developers should tag targets with `tags=["requires-network"]` to opt-out of the enforcement.
# Docs: https://bazel.build/reference/command-line-reference#flag--sandbox_default_allow_network
build --sandbox_default_allow_network=false

# Warn if a test's timeout is significantly longer than the test's actual execution time.
# Bazel's default for test_timeout is medium (5 min), but most tests should instead be short (1 min).
# While a test's timeout should be set such that it is not flaky, a test that has a highly
# over-generous timeout can hide real problems that crop up unexpectedly.
# For instance, a test that normally executes in a minute or two should not have a timeout of
# ETERNAL or LONG as these are much, much too generous.
# Docs: https://bazel.build/docs/user-manual#test-verbose-timeout-warnings
test --test_verbose_timeout_warnings

# Allow the Bazel server to check directory sources for changes. Ensures that the Bazel server
# notices when a directory changes, if you have a directory listed in the srcs of some target.
# Recommended when using
# [copy_directory](https://github.com/bazel-contrib/bazel-lib/blob/main/docs/copy_directory.md) and
# [rules_js](https://github.com/aspect-build/rules_js) since npm package are source directories
# inputs to copy_directory actions.
# Docs: https://bazel.build/reference/command-line-reference#flag--host_jvm_args
startup --host_jvm_args=-DBAZEL_TRACK_SOURCE_DIRECTORIES=1

# Allow exclusive tests to run in the sandbox. Fixes a bug where Bazel doesn't enable sandboxing for
# tests with `tags=["exclusive"]`.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_exclusive_test_sandboxed
test --incompatible_exclusive_test_sandboxed

# Use a static value for `PATH` and does not inherit `LD_LIBRARY_PATH`. Doesn't let environment
# variables like `PATH` sneak into the build, which can cause massive cache misses when they change.
# Use `--action_env=ENV_VARIABLE` if you want to inherit specific environment variables from the
# client, but note that doing so can prevent cross-user caching if a shared cache is used.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_strict_action_env
build --incompatible_strict_action_env

# Propagate tags from a target declaration to the actions' execution requirements.
# Ensures that tags applied in your BUILD file, like `tags=["no-remote"]`
# get propagated to actions created by the rule.
# Without this option, you rely on rules authors to manually check the tags you passed
# and apply relevant ones to the actions they create.
# See https://github.com/bazelbuild/bazel/issues/8830 for details.
# Docs: https://bazel.build/reference/command-line-reference#flag--experimental_allow_tags_propagation
build --experimental_allow_tags_propagation
fetch --experimental_allow_tags_propagation
query --experimental_allow_tags_propagation

# Do not automatically create `__init__.py` files in the runfiles of Python targets. Fixes the wrong
# default that comes from Google's internal monorepo by using `__init__.py` to delimit a Python
# package. Precisely, when a `py_binary` or `py_test` target has `legacy_create_init` set to `auto (the
# default), it is treated as false if and only if this flag is set. See
# https://github.com/bazelbuild/bazel/issues/10076.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_default_to_explicit_init_py
build --incompatible_default_to_explicit_init_py

# Set default value of `allow_empty` to `False` in `glob()`. This prevents a common mistake when
# attempting to use `glob()` to match files in a subdirectory that is opaque to the current package
# because it contains a BUILD file. See https://github.com/bazelbuild/bazel/issues/8195.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_disallow_empty_glob
common --incompatible_disallow_empty_glob

# Always download coverage files for tests from the remote cache. By default, coverage files are not
# downloaded on test result cache hits when --remote_download_minimal is enabled, making it impossible
# to generate a full coverage report.
# Docs: https://bazel.build/reference/command-line-reference#flag--experimental_fetch_all_coverage_outputs
# detching remote cache results
test --experimental_fetch_all_coverage_outputs

Convenience options

We usually like to enable these to make things easier.

convenience.bazelrc

# Attempt to build & test every target whose prerequisites were successfully built.
# Docs: https://bazel.build/docs/user-manual#keep-going
build --keep_going

# Output test errors to stderr so users don't have to `cat` or open test failure log files when test
# fail. This makes the log noisier in exchange for reducing the time-to-feedback on test failures for
# users.
# Docs: https://bazel.build/docs/user-manual#test-output
test --test_output=errors

# Show the output files created by builds that requested more than one target. This helps users
# locate the build outputs in more cases
# Docs: https://bazel.build/docs/user-manual#show-result
build --show_result=20

# Bazel picks up host-OS-specific config lines from bazelrc files. For example, if the host OS is
# Linux and you run bazel build, Bazel picks up lines starting with build:linux. Supported OS
# identifiers are `linux`, `macos`, `windows`, `freebsd`, and `openbsd`. Enabling this flag is
# equivalent to using `--config=linux` on Linux, `--config=windows` on Windows, etc.
# Docs: https://bazel.build/reference/command-line-reference#flag--enable_platform_specific_config
common --enable_platform_specific_config

# Output a heap dump if an OOM is thrown during a Bazel invocation
# (including OOMs due to `--experimental_oom_more_eagerly_threshold`).
# The dump will be written to `<output_base>/<invocation_id>.heapdump.hprof`.
# You may need to configure CI to capture this artifact and upload for later use.
# Docs: https://bazel.build/reference/command-line-reference#flag--heap_dump_on_oom
common --heap_dump_on_oom

Performance options

Making Bazel faster requires careful tuning. These flags generally help.

performance.bazelrc

# Directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.
# Save time on Sandbox creation and deletion when many of the same kind of action run during the
# build.
# No longer experimental in Bazel 6: https://github.com/bazelbuild/bazel/commit/c1a95501a5611878e5cc43a3cc531f2b9e47835b
# Docs: https://bazel.build/reference/command-line-reference#flag--reuse_sandbox_directories
build --experimental_reuse_sandbox_directories

# Do not build runfiles symlink forests for external repositories under
# `.runfiles/wsname/external/repo` (in addition to `.runfiles/repo`). This reduces runfiles &
# sandbox creation times & prevents accidentally depending on this feature which may flip to off by
# default in the future. Note, some rules may fail under this flag, please file issues with the rule
# author.
# Docs: https://bazel.build/reference/command-line-reference#flag--legacy_external_runfiles
build --nolegacy_external_runfiles

# Avoid creating a runfiles tree for binaries or tests until it is needed.
# Docs: https://bazel.build/reference/command-line-reference#flag--build_runfile_links
# See https://github.com/bazelbuild/bazel/issues/6627
#
# This may break local workflows that `build` a binary target, then run the resulting program
# outside of `bazel run`. In those cases, the script will need to call
# `bazel build --build_runfile_links //my/binary:target` and then execute the resulting program.
build --nobuild_runfile_links

# Needed prior to Bazel 8; see
# https://github.com/bazelbuild/bazel/issues/20577
coverage --build_runfile_links

Debug options

Users can run bazel test --config=debug to enable these flags that change the way tests are executed.

debug.bazelrc

############################################################
# Use `bazel test --config=debug` to enable these settings #
############################################################

# Stream stdout/stderr output from each test in real-time.
# Docs: https://bazel.build/docs/user-manual#test-output
test:debug --test_output=streamed

# Run one test at a time.
# Docs: https://bazel.build/reference/command-line-reference#flag--test_strategy
test:debug --test_strategy=exclusive

# Prevent long running tests from timing out.
# Docs: https://bazel.build/docs/user-manual#test-timeout
test:debug --test_timeout=9999

# Always run tests even if they have cached results.
# Docs: https://bazel.build/docs/user-manual#cache-test-results
test:debug --nocache_test_results

Options for running on CI

ci.bazelrc

# Set this flag to enable re-tries of failed tests on CI.
# When any test target fails, try one or more times. This applies regardless of whether the "flaky"
# tag appears on the target definition.
# This is a tradeoff: legitimately failing tests will take longer to report,
# but we can paper over flaky tests that pass most of the time.
# The alternative is to mark every flaky test with the `flaky = True` attribute, but this requires
# the buildcop to make frequent code edits.
# Not recommended for local builds so that the flakiness is observed during development and thus
# is more likely to get fixed.
# Note that when passing after the first attempt, Bazel will give a special "FLAKY" status.
# Docs: https://bazel.build/docs/user-manual#flaky-test-attempts
test --flaky_test_attempts=2

# Announce all announces command options read from the bazelrc file(s) when starting up at the
# beginning of each Bazel invocation. This is very useful on CI to be able to inspect what Bazel rc
# settings are being applied on each run.
# Docs: https://bazel.build/docs/user-manual#announce-rc
build --announce_rc

# Add a timestamp to each message generated by Bazel specifying the time at which the message was
# displayed.
# Docs: https://bazel.build/docs/user-manual#show-timestamps
build --show_timestamps

# Only show progress every 60 seconds on CI.
# We want to find a compromise between printing often enough to show that the build isn't stuck,
# but not so often that we produce a long log file that requires a lot of scrolling.
# https://bazel.build/reference/command-line-reference#flag--show_progress_rate_limit
build --show_progress_rate_limit=60

# Use cursor controls in screen output.
# Docs: https://bazel.build/docs/user-manual#curses
build --curses=yes

# Use colors to highlight output on the screen. Set to `no` if your CI does not display colors.
# Docs: https://bazel.build/docs/user-manual#color
build --color=yes

# The terminal width in columns. Configure this to override the default value based on what your CI system renders.
# Docs: https://github.com/bazelbuild/bazel/blob/1af61b21df99edc2fc66939cdf14449c2661f873/src/main/java/com/google/devtools/build/lib/runtime/UiOptions.java#L151
build --terminal_columns=143

######################################
# Generic remote cache configuration #
######################################

# Only download remote outputs of top level targets to the local machine.
# Docs: https://bazel.build/reference/command-line-reference#flag--remote_download_toplevel
build --remote_download_toplevel

# The maximum amount of time to wait for remote execution and cache calls.
# https://bazel.build/reference/command-line-reference#flag--remote_timeout
build --remote_timeout=3600

# Upload locally executed action results to the remote cache.
# Docs: https://bazel.build/reference/command-line-reference#flag--remote_upload_local_results
build --remote_upload_local_results

# Fall back to standalone local execution strategy if remote execution fails. If the grpc remote
# cache connection fails, it will fail the build, add this so it falls back to the local cache.
# Docs: https://bazel.build/reference/command-line-reference#flag--remote_local_fallback
build --remote_local_fallback

# Fixes builds hanging on CI that get the TCP connection closed without sending RST packets.
# Docs: https://bazel.build/reference/command-line-reference#flag--grpc_keepalive_time
build --grpc_keepalive_time=30s

Options for Java

java.bazelrc

# Aspect recommended Bazel flags when using rules_java and rules_jvm_external

# Pin java versions to desired language level
# See https://bazel.build/docs/bazel-and-java#java-versions
# and https://en.wikipedia.org/wiki/Java_version_history

# What version of Java are the source files in this repo?
# See https://bazel.build/docs/user-manual#java-language-version
common --java_language_version=17

# The Java language version used to build tools that are executed during a build
# See https://bazel.build/docs/user-manual#tool-java-language-version
common --tool_java_language_version=17

# The version of JVM to use to execute the code and run the tests.
# NB: The default value is local_jdk which is non-hermetic.
# See https://bazel.build/docs/user-manual#java-runtime-version
common --java_runtime_version=remotejdk_17

# The version of JVM used to execute tools that are needed during a build.
# See https://bazel.build/docs/user-manual#tool-java-runtime-version
common --tool_java_runtime_version=remotejdk_17

# Repository rules, such as rules_jvm_external: put Bazel's JDK on the path.
# Avoids non-hermeticity from dependency on a JAVA_HOME pointing at a system JDK
# see https://github.com/bazelbuild/rules_jvm_external/issues/445
common --repo_env=JAVA_HOME=../bazel_tools/jdk

Options for JavaScript

We suggest using these when using Aspect's rules_js.

javascript.bazelrc

# Aspect recommended Bazel flags when using Aspect's JavaScript rules: https://github.com/aspect-build/rules_js
# Docs for Node.js flags: https://nodejs.org/en/docs/guides/debugging-getting-started/#command-line-options

# Support for debugging Node.js tests. Use bazel run with `--config=debug` to turn on the NodeJS
# inspector agent. The node process will break before user code starts and wait for the debugger to
# connect. Pass the --inspect-brk option to all tests which enables the node inspector agent. See
# https://nodejs.org/de/docs/guides/debugging-getting-started/#command-line-options for more
# details.
# Docs: https://nodejs.org/en/docs/guides/debugging-getting-started/#command-line-options
run:debug -- --node_options=--inspect-brk
test:debug --test_env=NODE_OPTIONS=--inspect-brk

Options introduced in Bazel 7.0

Once you've upgraded to Bazel 7, you may want these options.

bazel7.bazelrc

# Speed up all builds by not checking if external repository files have been modified.
# Docs: https://github.com/bazelbuild/bazel/blob/1af61b21df99edc2fc66939cdf14449c2661f873/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java#L244
common --noexperimental_check_external_repository_files

# Don't report when the root module's lower bound for a dependency happens to be less than the resolved version.
# This is expected and should NOT prompt an engineer to update our lower bound to match.
# WARNING: For repository 'aspect_bazel_lib', the root module requires module version aspect_bazel_lib@1.30.2,
# but got aspect_bazel_lib@1.31.2 in the resolved dependency graph.
common --check_direct_dependencies=off

# Directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.
# Save time on Sandbox creation and deletion when many of the same kind of action run during the
# build.
# Docs: https://bazel.build/reference/command-line-reference#flag--reuse_sandbox_directories
build --reuse_sandbox_directories

Options introduced in Bazel 6.0

Once you've upgraded to Bazel 6, you may want these options.

bazel6.bazelrc

# Speed up all builds by not checking if external repository files have been modified.
# Docs: https://github.com/bazelbuild/bazel/blob/1af61b21df99edc2fc66939cdf14449c2661f873/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java#L244
build --noexperimental_check_external_repository_files
fetch --noexperimental_check_external_repository_files
query --noexperimental_check_external_repository_files

# Directories used by sandboxed non-worker execution may be reused to avoid unnecessary setup costs.
# Save time on Sandbox creation and deletion when many of the same kind of action run during the
# build.
# Docs: https://bazel.build/reference/command-line-reference#flag--reuse_sandbox_directories
build --reuse_sandbox_directories

# Avoid this flag being enabled by remote_download_minimal or remote_download_toplevel
# See https://meroton.com/blog/bazel-6-errors-build-without-the-bytes/
build --noexperimental_action_cache_store_output_metadata

# Speed up all builds by not checking if output files have been modified. Lets you make changes to
# the output tree without triggering a build for local debugging. For example, you can modify
# [rules_js](https://github.com/aspect-build/rules_js) 3rd party npm packages in the output tree
# when local debugging.
# Docs: https://github.com/bazelbuild/bazel/blob/1af61b21df99edc2fc66939cdf14449c2661f873/src/main/java/com/google/devtools/build/lib/pkgcache/PackageOptions.java#L185
# NB: This flag is in bazel6.bazelrc as when used in Bazel 7 is has been observed to break
# "build without the bytes" --remote_download_outputs=toplevel. See https://github.com/bazel-contrib/bazel-lib/pull/711
# for more info.
build --noexperimental_check_output_files
fetch --noexperimental_check_output_files
query --noexperimental_check_output_files

# Don't apply `--noremote_upload_local_results` and `--noremote_accept_cached` to the disk cache.
# If you have both `--noremote_upload_local_results` and `--disk_cache`, then this fixes a bug where
# Bazel doesn't write to the local disk cache as it treats as a remote cache.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_remote_results_ignore_disk
# NB: This flag is in bazel6.bazelrc because it became a no-op in Bazel 7 and has been removed
# in Bazel 8.
build --incompatible_remote_results_ignore_disk

Options for Bazel 5 or before

If you're stuck on an older Bazel, you might want these options:

bazel5.bazelrc

# Performance improvement for WORKSPACE evaluation
# of slow rulesets, for example rules_k8s has been
# observed to take 10 seconds without this flag.
# See https://github.com/bazelbuild/bazel/issues/13907
common --incompatible_existing_rules_immutable_view

Communicating with users

Need to broadcast a message to all your Bazel users? You can use

build --unconditional_warning="You can just get it to print stuff" --unconditional_warning="<0001f92f>, anything"

to get a UI like

WARNING: You can just get it to print stuff
WARNING: 🤯, anything

Notes

build --incompatible_remote_build_event_upload_respect_no_cache: Don't upload artifacts referenced in the BEP if the action can't be cached remotely. incompatible_remote_build_event_upload_respect_no_cache is deprecated in Bazel 6. in favor of --experimental_remote_build_event_upload=minimal.

build --experimental_inprocess_symlink_creation: allows spaces in filenames which are inputs to actions.

test --build_tests_only: change the behavior of bazel test to not bother building targets which aren't dependencies of the tests. Matches some developer expectations.

Not recommended: build --workspace_status_command=path/to/script: This should only be enabled for release builds where stamping is desirable, otherwise you spend time running git commands on every build. Consider build:release --workspace_status_command=... instead, so it's only active under --config=release.