Skip to main content

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".

RC file layout

The .bazelrc file will 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. For example, the aspect init command creates a file like this:

.bazelrc
# Import Aspect recommended correctness settings
import %workspace%/.aspect/bazelrc/correctness.bazelrc

# ... import more shared bazelrc files...

### YOUR PROJECT SPECIFIC SETTINGS 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

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
test --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/aspect-build/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

# Checking the ctime of input files of an action before uploading it to a remote cache. Prevents
# concurrent local file modification from poisoning the build cache.
# Docs: https://bazel.build/reference/command-line-reference#flag--experimental_guard_against_concurrent_changes
build --experimental_guard_against_concurrent_changes

# 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

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
test --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 noiser 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
build --enable_platform_specific_config
fetch --enable_platform_specific_config
test --enable_platform_specific_config
query --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
build --heap_dump_on_oom

Performance options

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

performance.bazelrc
# Merkle tree calculations will be memoized to improve the remote cache hit checking speed. The
# memory foot print of the cache is controlled by `--experimental_remote_merkle_tree_cache_size`.
# Docs: https://bazel.build/reference/command-line-reference#flag--experimental_remote_merkle_tree_cache
build --experimental_remote_merkle_tree_cache
query --experimental_remote_merkle_tree_cache

# The number of Merkle trees to memoize to improve the remote cache hit checking speed. Even though
# the cache is automatically pruned according to Java's handling of soft references, out-of-memory
# errors can occur if set too high. If set to 0 the cache size is unlimited. Optimal value varies
# depending on project's size.
# Docs: https://bazel.build/reference/command-line-reference#flag--experimental_remote_merkle_tree_cache_size
build --experimental_remote_merkle_tree_cache_size=1000
query --experimental_remote_merkle_tree_cache_size=1000

# 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
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
build --incompatible_remote_results_ignore_disk

# 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
run --nolegacy_external_runfiles
test --nolegacy_external_runfiles

# Some actions are always IO-intensive but require little compute. It's wasteful to put the output
# in the remote cache, it just saturates the network and fills the cache storage causing earlier
# evictions. It's also not worth sending them for remote execution.
# For actions like PackageTar it's usually faster to just re-run the work locally every time.
# You'll have to look at an execution log to figure out what other action mnemonics you care about.
# In some cases you may need to patch rulesets to add a mnemonic to actions that don't have one.
# https://bazel.build/reference/command-line-reference#flag--modify_execution_info
build --modify_execution_info=PackageTar=+no-remote

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
# We recommend enforcing a policy that keeps your CI from being slowed down
# by individual test targets that should be optimized
# or split up into multiple test targets with sharding or manually.
# Set this flag to exclude targets that have their timeout set to eternal (>15m) from running on CI.
# Docs: https://bazel.build/docs/user-manual#test-timeout-filters
build --test_timeout_filters=-eternal

# 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
build --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.
# Docs: https://bazel.build/reference/command-line-reference#flag--progress_report_interval
build --progress_report_interval=60

# Only show progress every 60 seconds on CI.
# https://bazel.build/reference/command-line-reference#flag--show_progress_rate_limit
build --show_progress_rate_limit=60

# Don't use cursor controls in its screen output.
# Docs: https://bazel.build/docs/user-manual#curses
build --curses=no

# Use colors to highlight its 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=80

######################################
# 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 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

# Enable runfiles on all platforms. Runfiles are on by default on Linux and MacOS but off on
# Windows.
#
# In general, rules_js and derivate rule sets assume that runfiles are enabled and do not support no
# runfiles case because it does not scale to teach all Node.js tools to use the runfiles manifest.
#
# If you are developing on Windows, you must either run bazel with administrator privileges or
# enable developer mode. If you do not you may hit this error on Windows:
#
# Bazel needs to create symlinks to build the runfiles tree.
# Creating symlinks on Windows requires one of the following:
# 1. Bazel is run with administrator privileges.
# 2. The system version is Windows 10 Creators Update (1703) or later
# and developer mode is enabled.
#
# Docs: https://bazel.build/reference/command-line-reference#flag--enable_runfiles
build --enable_runfiles

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

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.