Bazelisk Documentation

If a tools/bazel wrapper is present in your project, Bazelisk will execute it instead of the downloaded Bazel binary.

Supported wrapper types (in order of priority):

1. tools/bazel.<OSNAME>-<ARCH>[.exe]
2. tools/bazel.<ARCH>[.exe]
3. tools/bazel[.exe]
4. tools/bazel.ps1 (Windows PowerShell)
5. tools/bazel.bat (Windows Batch)

Bazelisk sets the BAZEL_REAL environment variable, which the wrapper can use to execute the actual downloaded Bazel binary. To disable this behavior, set BAZELISK_SKIP_WRAPPER to any non-empty value.

Bazelisk can be installed on various platforms using package managers or by downloading the binary manually.

• macOS: Use Homebrew.
• Windows: Use winget, choco, or scoop.
• Linux: Download the binary from the GitHub Releases page and add it to your PATH.
• npm: Frontend developers can install it globally via npm.
• mise: Use mise for polyglot tool management.

Once installed, Bazelisk adds both bazelisk and bazel to your PATH.

# macOS
brew install bazelisk

# Windows
winget install Bazel.Bazelisk
choco install bazelisk
scoop install bazelisk

# npm
npm install -g @bazel/bazelisk

# mise
mise use -g bazelisk@latest

To install the Go version of Bazelisk, use the go install command. After installation, ensure the Go bin directory is in your PATH to run the bazelisk command directly.

go install github.com/bazelbuild/bazelisk@latest
export PATH=$PATH:$(go env GOPATH)/bin

To ensure developers use Bazelisk instead of a standard Bazel installation (which might mismatch the version pinned in .bazelversion), you can implement a check in your repository's wrapper script (e.g., tools/bazel).

Bazelisk sets the environment variable BAZELISK_SKIP_WRAPPER=true when it calls the wrapper. If this variable is not present, it means the user is calling your wrapper directly instead of through Bazelisk, and you should report an error instructing them to install Bazelisk.

You can set environment variables persistently using a .bazeliskrc file located in the workspace root or the user home directory.

Precedence Order:

1. Environment variables
2. Workspace root .bazeliskrc
3. User home .bazeliskrc

Example .bazeliskrc content:

USE_BAZEL_VERSION=0.19.0
BAZELISK_GITHUB_TOKEN=abc

By default, Bazelisk retrieves binaries from Google Cloud Storage. You can override this behavior using environment variables:

• BAZELISK_BASE_URL: Overrides the base URL. Bazelisk appends /<VERSION>/<FILENAME> to this value. It uses ~/.netrc for Basic authentication.
• BAZELISK_FORMAT_URL: Overrides the entire URL format using a template string with placeholders:
  • %e: Extension suffix (e.g., .exe or empty).
  • %h: Value of BAZELISK_VERIFY_SHA256.
  • %m: Machine architecture (e.g., arm64, x86_64).
  • %o: Operating system (e.g., darwin, linux).
  • %v: Determined Bazel version.
  • %%: Literal %.
• BAZELISK_VERIFY_SHA256: Used to validate downloaded artifacts against a SHA256 value.

The following keys can be defined in a .bazeliskrc file:

• BAZELISK_BASE_URL
• BAZELISK_FORMAT_URL
• BAZELISK_NOJDK
• BAZELISK_CLEAN
• BAZELISK_GITHUB_TOKEN
• BAZELISK_HOME_DARWIN
• BAZELISK_HOME_LINUX
• BAZELISK_HOME_WINDOWS
• BAZELISK_HOME
• BAZELISK_INCOMPATIBLE_FLAGS
• BAZELISK_SHOW_PROGRESS
• BAZELISK_SHUTDOWN
• BAZELISK_SKIP_WRAPPER
• BAZELISK_USER_AGENT
• BAZELISK_VERIFY_SHA256
• USE_BAZEL_VERSION

Bazelisk sets specific environment variables that can be used by your build scripts or tools:

• BAZELISK: Contains the path to the Bazelisk binary itself. Use this to detect if a process is running under Bazelisk or to run specific Bazel versions from within a Bazel run.
• PATH modification: Bazelisk prepends a directory containing the downloaded Bazel binary to your PATH. This ensures that any sub-processes invoking bazel use the same version as the parent invocation.

Bazelisk supports several versioning formats:

• latest: The latest stable (LTS) version. Use latest-1, latest-2, etc., for previous releases.
• Exact version: e.g., 0.17.2, 0.20.0rc3 (release candidate), or 5.0.0-pre.20210317.1 (rolling).
• Floating version: 4.x returns the latest release from the LTS series started by Bazel 4.0.0.
• Wildcard version: 4.* returns the latest release or candidate from the LTS series started by Bazel 4.0.0.
• Git Hash: A specific commit hash (must have passed Bazel CI).

Special official release names (not supported for forks):

• last_green: The most recent commit that passed Bazel CI.
• last_rc: The most recent release candidate.
• rolling: The latest rolling release.

Bazelisk provides a completion command to generate completion scripts for various shells. Note that the generated script is tied to the active Bazel version.

Bash

To use Bash completion, you can either source it directly in your workspace or save it to a file:

# Direct source
source <(bazelisk completion bash)

# Save to file and add to system paths
bazelisk completion bash > bash-complete.bash

Fish

Save the completion script into your fish completion directory:

bazelisk completion fish > ~/.config/fish/completions/bazel.fish