Repository Root

With Bazelisk and .bazelversion handling the build tool itself (0.1.1 Bazelisk & .bazelversion), the next file to look for is the one that marks where the project begins. Every Bazel project needs a root — a single directory that anchors the entire build. Bazel finds this root by looking for a boundary marker file¹. Without one, Bazel doesn't know where your project begins, and no command will work.

The Boundary Marker Files

Three file types can serve as a repository boundary marker²:

Multiple marker files can coexist in the same directory². In practice, a modern project usually has a MODULE.bazel at the root and may also have a REPO.bazel beside it.

A typical project root looks like this:

my-project/
├── .bazelversion
├── .git/
├── MODULE.bazel
├── REPO.bazel          (optional)
├── BUILD.bazel
├── app/
│   ├── BUILD.bazel
│   └── main.cc
└── lib/
    ├── BUILD.bazel
    └── utils.cc

The .bazelversion file from the previous article, a boundary marker such as MODULE.bazel, and BUILD.bazel files in directories — which create packages, covered next in 0.1.3 Package.

MODULE.bazel

This file serves two purposes⁴:

1. Root marker — tells Bazel where the repository begins.
2. Dependency declaration — lists external modules the project depends on.

A minimal MODULE.bazel can be empty — just its presence is enough to mark the root. A typical one looks like this:

module(name = "my-project", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.2.17")
bazel_dep(name = "platforms", version = "1.0.0")

How bazel_dep() works, version resolution, and the Bazel Central Registry are covered in 3.1 Dependency Management. At this stage, just know that MODULE.bazel sits at the root and anchors everything else.

REPO.bazel

REPO.bazel is also a repository boundary file². Like MODULE.bazel, it can be empty and still mark the root. Its extra job is to set repo-wide defaults for all build targets. For example, applying a common license to all targets:

repo(
    default_package_metadata = ["//:my_license"],
)

It also provides ignore_directories() to exclude directories from Bazel's view (e.g., node_modules)⁵ — the modern replacement for .bazelignore, covered in 3.2.2 .bazelignore.

In modern Bzlmod-based projects, REPO.bazel usually complements MODULE.bazel rather than replacing it. MODULE.bazel carries module and dependency declarations; REPO.bazel carries repo-wide defaults. The important mental model is simply that either file counts as a boundary marker.

WORKSPACE (Removed)

Before Bzlmod, the WORKSPACE file was Bazel's only root marker and dependency management mechanism. It required all transitive dependencies to be declared manually, leading to fragile and verbose configurations². It was replaced by MODULE.bazel, disabled by default in Bazel 8, and fully removed in Bazel 9³. A variant named WORKSPACE.bazel also existed, for the same case-sensitivity reasons that BUILD.bazel is preferred over BUILD (covered in 0.1.3 Package).

If you encounter a WORKSPACE file in an existing project, it's a sign the project hasn't migrated to Bzlmod yet — see M1 WORKSPACE → Bzlmod.

One Bazel Repo ≈ One Git Repo

A Bazel repository and a Git repository are typically one-to-one — the MODULE.bazel sits at the same level as .git/⁵. Nesting multiple Bazel repositories inside one Git repository, or placing a Bazel repository in a subdirectory, is possible but unusual and generally discouraged⁴. Bazel calls this directory tree a repository. The related term workspace, common in older documentation, has a slightly different meaning — the distinction becomes relevant when working with external dependencies and labels (0.2.1 Label Anatomy).