Bazelisk is a user-friendly launcher and wrapper for Bazel Build System that automatically downloads and executes the requested Bazel version based on project configuration files or environment variables.
When executed, Bazelisk checks for the appropriate Bazel version in:
USE_BAZEL_VERSION environment variable..bazelversion file in the workspace directory.Bazelisk then downloads the official pre-compiled upstream binary from GitHub Releases into the user cache directory (~/.cache/bazelisk/downloads/...) and executes it.
For Nix Package Manager projects and systems running NixOS, Bazelisk is not recommended.
Official Bazel binary distributions downloaded by Bazelisk are compiled for generic Linux distributions and hardcode the standard ELF dynamic linker path (/lib64/ld-linux-x86-64.so.2). Because NixOS uses non-standard library paths in the Nix store without standard FHS locations, executing binaries downloaded by Bazelisk fails immediately with:
Could not start dynamically linked executable: /home/.../.cache/bazelisk/downloads/.../bin/bazel
NixOS cannot run dynamically linked executables intended for generic linux environments out of the box.
For more information, see: https://nix.dev/permalink/stub-ld
In a Nix-enabled project (such as one with flake.nix), Bazelisk should not be used. Instead, the appropriate Bazel package (e.g. pkgs.bazel_8) should simply be placed directly on the development shell (devShells.default):
packages = with pkgs; [
bazel_8
];
This ensures that:
bazel binary on PATH is natively built, patched with patchelf to link against Nix store libraries, and runs reliably on NixOS and non-NixOS Linux distributions alike.flake.nix and locked via flake.lock, eliminating the need for a separate .bazelversion file.