Bazel flag cheat sheet

Navigating Bazel’s extensive list of command line flags can be a challenge. This page focuses on the most crucial flags you’ll need to know.

Useful general options

The following flags are meant to be set explicitly on the command line.

--config

See —config in the command-line reference

You can organize flags in a .bazelrc file into configurations, like ones for debugging or release builds. Additional configuration groups can be selected with —config=<group>.

--keep_going

See —keep_going in the command-line reference

Bazel should try as much as possible to continue with build and test execution. By default, Bazel fails eagerly.

--remote_download_outputs

See —remote_download_outputs in the command-line reference

When using remote execution or caching (both disk and remote), you can signal to Bazel that you want to download all (intermediate) build artifacts as follows:

—remote_download_outputs=all

By default, Bazel only downloads top-level artifacts, such as the final binary, and intermediate artifacts that are necessary for local actions.

--stamp

See —stamp in the command-line reference

Adds build info (user, timestamp) to binaries.

Uncover Build & Test Issues

The following flags can help you better understand Bazel build or test errors.

--announce_rc

See —announce_rc in the command-line reference

Shows which flags are implicitly set through user-defined, machine-defined, or project-defined .bazelrc files.

--auto_output_filter

See —auto_output_filter in the command-line reference

By default, Bazel tries to prevent log spam and does only print compiler warnings and Starlark debug output for packages and subpackages requested on the command line. To disable all filtering, set —auto_output_filter=none.

--sandbox_debug

See —sandbox_debug in the command-line reference

Lets you drill into sandboxing errors. For details on why Bazel sandboxes builds by default and what gets sandboxed, see our sandboxing documentation.

--subcommands (-s)

See —subcommands (-s) in the command-line reference

Displays a comprehensive list of every command that Bazel runs during a build, regardless of whether it succeeds or fails

Startup

Caution: Startup flags need to be passed before the command and cause a server restart. Toggle these flags with caution.

--bazelrc

See —bazelrc in the command-line reference

You can specify default Bazel options in .bazelrc files. If multiple .bazelrc files exist, you can select which .bazelrc file is used by adding —bazelrc=<path to the .bazelrc file>.

--host_jvm_args

See —host_jvm_args in the command-line reference

Limits the amount of RAM the Bazel server uses.

For example, the following limits the Bazel heap size to 3GB:

—host_jvm_args=-Xmx3g

--output_base

See —output_base in the command-line reference

Controls Bazel’s output tree. Bazel doesn’t store build outputs, including logs, within the source tree itself. Instead, it uses a distinct output tree for this purpose.

Bazel tests

The following flags are related to Bazel test

--java_debug

See —java_debug in the command-line reference

Causes Java tests to wait for a debugger connection before being executed.

--runs_per_test

See —runs_per_test in the command-line reference

The number of times to run tests. For example, to run tests N times, add —runs_per_test=N. This can be useful to debug flaky tests and see whether a fix causes a test to pass consistently.

--test_filter

See —test_filter in the command-line reference

This flag is particularly useful when iterating on a single test method, such as when a change you made breaks a test. Instead of re-running all the test methods in the test suite, you can focus solely on the specific test(s) that failed. This allows for faster feedback and more efficient debugging. This flag is often used in conjunction with —test_output=streamed for real-time test output.

--test_output

See —test_output in the command-line reference

Specifies the output mode. By default, Bazel captures test output in local log files. When iterating on a broken test, you typically want to use —test_output=streamed to see the test output in real time.

Bazel run

The following flags are related to Bazel run.

--run_under

See —run_under in the command-line reference

Changes how executables are invoked. For example —run_under=“strace -c” is commonly used for debugging.

User-specific bazelrc options

The following flags are related to user-specific .bazelrc options.

--disk_cache

See —disk_cache in the command-line reference

A path to a directory where Bazel can read and write actions and action outputs. If the directory doesn’t exist, it will be created.

You can share build artifacts between multiple branches or workspaces and speed up Bazel builds by adding —disk_cache=<path> to your command.

--jobs

See —jobs in the command-line reference

The number of concurrent jobs to run.

This is typically only required when using remote execution where a remote build cluster executes more jobs than you have cores locally.

--local_resources

See —local_resources in the command-line reference

Limits how much CPU or RAM is consumed by locally running actions.

--sandbox_base

See —sandbox_base in the command-line reference

Lets the sandbox create its sandbox directories underneath this path. By default, Bazel executes local actions sandboxed which adds some overhead to the build.

Project-specific bazelrc options

The following flags are related to project-specific .bazelrc options.

--flaky_test_attempts

See —flaky_test_attempts in the command-line reference

Retry each test up to the specified number of times in case of any test failure. This is especially useful on Continuous Integration. Tests that require more than one attempt to pass are marked as FLAKY in the test summary.

--remote_cache

See —remote_cache in the command-line reference

A URI of a caching endpoint. Setting up remote caching can be a great way to speed up Bazel builds. It can be combined with a local disk cache.

--remote_download_regex

See —remote_download_regex in the command-line reference

Force remote build outputs whose path matches this pattern to be downloaded, irrespective of the —remote_download_outputs setting. Multiple patterns may be specified by repeating this flag.

--remote_executor

See —remote_executor in the command-line reference

HOST or HOST:PORT of a remote execution endpoint. Pass this if you are using a remote execution service. You’ll often need to Add —remote_instance_name=<name>.

--remote_instance_name

See —remote_instance_name in the command-line reference

The value to pass as instance_name in the remote execution API.

--show_timestamps

See —show_timestamps in the command-line reference

If specified, a timestamp is added to each message generated by Bazel specifying the time at which the message was displayed. This is useful on CI systems to quickly understand what step took how long.

--spawn_strategy

See —spawn_strategy in the command-line reference

Even with remote execution, running some build actions locally might be faster. This depends on factors like your build cluster’s capacity, network speed, and network delays.