3.1.1 Bzlmod (MODULE.bazel)
Bzlmod is Bazel's module-based dependency system. Instead of building external dependency state by imperatively running repository rules in WORKSPACE, the root of the repo declares direct dependencies in MODULE.bazel, Bazel asks registries for the referenced modules' own MODULE.bazel files, resolves the whole graph once, and then turns the result into external repositories that BUILD files can use.1,2 That separation is why modern Bazel dependency management feels more like a package manager and less like a bootstrapping script.
MODULE.bazel declares intent, not the whole closure
A typical root module names the project and lists only the modules it directly depends on:
module(name = "acme", version = "1.0")
bazel_dep(name = "rules_java", version = "8.6.4")
bazel_dep(name = "protobuf", version = "29.3")
That is intentionally shorter than the old WORKSPACE pattern. You do not spell out the full transitive closure yourself. Bazel starts from the root MODULE.bazel, recursively reads dependency modules from registries, and only then decides which versions to use.1,2 By default those modules come from the Bazel Central Registry. Details about mirrors and downloader policy come later in 3.1.6 BCR Infrastructure. Custom registry hosting and registry layout live in 3.1.8 Registry Structure & Custom Registries.3 The maintainer-workspace MODULE.bazel is the same shape in a runnable repo: a single module() declaration, three bazel_dep() lines, and a local extension wired in with use_extension / use_repo.
Resolution is collective, not imperative
This is the biggest mental shift from 3.1.4 Legacy WORKSPACE Model. In the WORKSPACE world, transitive external dependencies were often reproduced manually or hidden inside helper macros, and the effective result could depend on ordering and convention.1,4 In Bzlmod, Bazel first discovers the full module graph and then resolves versions across that graph as one problem.1,2
The resolution algorithm is Minimal Version Selection (MVS). "Minimal" does not mean "pick the oldest thing in the registry." It means "pick the earliest version that satisfies all declared minimum requirements," which in practice is the highest version requested anywhere in the dependency graph, but not some newer release that nobody asked for.2,5 If one branch needs D 1.0 and another needs D 1.1, Bazel resolves to D 1.1. It does not silently jump to D 1.2 just because it exists.2,5
This default fits Bazel's broader one-version bias for third-party code. The normal outcome is one resolved version per module, which keeps the graph reproducible and avoids the "which copy did I really link against?" mess that grows around unmanaged diamonds.2,4 When you truly need an exception, you reach for an override instead of hoping transitive resolution will sort itself out.
Bazel itself can raise a requested version
Bazel ships a built-in module, bazel_tools, with dependency requirements of its own. Those requirements participate in MVS just like the requirements in your modules. If bazel_tools requests a higher version of a ruleset, Bazel can select that version even though your bazel_dep() still names an older one.2,6
Upgrading Bazel can therefore change a resolved ruleset version without an edit to MODULE.bazel. For example, a module declaring only bazel_dep(name = "rules_cc", version = "0.0.16") resolved as follows across three Bazel releases:6
| Bazel version | Resolved rules_cc version |
|---|---|
| 7.5.0 | 0.0.16 |
| 8.4.2 | 0.1.1 |
| 9.2.0 | 0.2.17 |
Built-in modules are hidden by default in bazel mod graph. Run bazel mod graph --include_builtin to see bazel_tools and its dependencies.7
Bazel warns by default when a direct dependency resolves to a different version than you requested. Use --check_direct_dependencies=error to turn that warning into a resolution failure.8
After resolution, modules become repositories
Bzlmod still ends up with repositories, because BUILD files and labels need repositories to point at. The difference is that repository definitions are produced after module resolution, not handwritten up front.1,2 That is why the same dependency system can give you a clean bazel_dep() interface while still materializing @rules_java//... or @protobuf//... labels for the build graph.1 Those labels ultimately attach to targets and edges in the build graph model from 2.1 Directed Acyclic Graph (DAG).
This also explains strict visibility. A module can directly see the repositories provided by its own bazel_dep() declarations, any extension-generated repositories it explicitly imports with use_repo(), and any repositories it declares locally with use_repo_rule().2,9 Transitive dependencies may exist in the resolved graph, but they are not meant to be casually referenced by name from arbitrary modules. That keeps external dependency usage closer to "declare what you use" instead of relying on whatever some intermediate dependency happened to pull in. The naming and mapping details show up later in 3.1.3 Repo Mapping.2
When a BUILD file reaches for a repository the root module never declared, the failure looks like an ordinary label error but the fix belongs in MODULE.bazel. The no-such-package-error snippet keeps that external-repo case separate from a missing local package so the two diagnostics do not blur together.
Overrides are the escape hatch
Most dependencies should be boring bazel_dep() declarations. Overrides exist for the cases that are not boring: pinning a version, forcing a different registry, applying patches, allowing multiple versions to coexist, or replacing a registry-backed module with an archive, Git repo, or local checkout.2,9
bazel_dep(name = "rules_python", version = "1.6.3")
local_path_override(module_name = "rules_python", path = "../rules_python")
The important constraint is that only the root module's overrides take effect.2,9 That makes overrides a deliberate maintainer tool, not something every transitive dependency can smuggle into your build. Use them here for local development, compatibility fixes, and brownfield migration. M1 WORKSPACE → Bzlmod develops the migration playbook, and 4.9 Repository Rules explains the repository-rule mechanics underneath these escape hatches.2,9
When a ruleset needs patched dependencies
Root-only overrides have a practical cost when a ruleset relies on patched dependencies. Its own overrides do not take effect in your build, so adding the ruleset does not automatically apply those patches.2,9
rules_applecross, which supports building for Apple platforms from Linux, illustrates this limitation. It uses single_version_override to patch rules_apple and apple_support. Its setup instructions ask you to copy those override blocks into your root MODULE.bazel and copy the patches/ directory into your repository.10
You therefore have to maintain the patch setup in your repository as well as declare the dependency.
Why MODULE.bazel stays declarative
MODULE.bazel is intentionally less programmable than WORKSPACE. It does not support load(), version ranges, or "latest" dependency declarations.11 The reason is architectural: Bazel starts from the local root MODULE.bazel, then resolves dependency modules by reading their MODULE.bazel files from registries before those source archives are fetched, so dependency declaration has to stay simple, inspectable, and reproducible.2,11
When you need programmable behavior, Bzlmod does not give up and fall back to ad hoc scripting. It moves that logic into module extensions. The common maintainer pattern is: declare a ruleset as a module, configure its extension with tags, then import the repositories that extension generates with use_repo().9,11
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
maven.install(artifacts = ["com.google.guava:guava:33.2.1-jre"])
use_repo(maven, "maven")
3.1.2 Using Extensions covers day-to-day use. Continue to 4.10 Authoring Module Extensions to author extensions, understand their evaluation model, and debug their implementation.9,11
The version you request with bazel_dep() is not necessarily the version your build will use. MVS can select a higher version to satisfy another module's requirement.2,5 bazel mod graph shows the resolved module graph, bazel mod explain <module> tells you why a module or version is present, and bazel mod show_repo <repo> shows the repository definition Bazel synthesized from that resolution.7 Keep MODULE.bazel.lock in version control as well: it records the registry inputs and extension outputs Bazel used, speeds up future resolution, and helps keep dependency state reproducible across the team.12 The maintainer-workspace MODULE.bazel.lock shows the on-disk shape — lockFileVersion, then registryFileHashes Bazel pinned during resolution. Pinning that resolved slice also reduces avoidable churn in the wider incremental graph described in 2.4 Caching & Incrementality. Unlike lockfiles in some package managers, the lockfile is not a list of every archive the build will download. It holds what Bazel needs to tell whether resolution must run again, and module extensions can decide their downloads in code. Offline preparation therefore starts from Bazel's own fetch, as 3.1.9 Offline / Air-Gapped Builds shows.12,13
Bzlmod separates declaration from resolution. MODULE.bazel says what your repo directly needs. Registries and MVS turn that into one resolved dependency graph. Bazel then materializes the repositories and extension-generated repos the build can actually reference. Once that model clicks, the rest of dependency management is mostly special cases: overrides when you need an escape hatch, extensions when a non-Bazel ecosystem must participate, and migration work when an old WORKSPACE world still has to coexist.
Check your understanding · 3 questions
1.Match each Bzlmod concept to its description:
Drag each answer onto the matching prompt, or click an answer and then click a prompt
2.True or false about MODULE.bazel and Bzlmod resolution:
Choose True or False for each sentence
3.Your root module declares bazel_dep(name = "rules_jvm_external", ...), then configures its maven extension with a list of artifacts. To reference @maven//:guava from a BUILD file, what additional MODULE.bazel directive is required?
Select one answer
Footnotes
-
External dependencies overview — root module flow, registry lookups, workspace/repository model, and WORKSPACE shortcomings ↩1 ↩2 ↩3 ↩4 ↩5 ↩6
-
Bazel modules —
MODULE.bazelas module manifest, MVS, overrides, and strict direct-dependency visibility ↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 -
Bazel registries — BCR as default index registry, module metadata, and
--registryselection behavior ↩ -
Dependency Management — WORKSPACE-era transitive dependency pain, one-version rule, and why scalable systems prefer collective resolution ↩1 ↩2
-
Minimal Version Selection (Go & Versioning, Part 4) — why MVS picks the minimal satisfying build list instead of arbitrarily newer versions ↩1 ↩2 ↩3
-
any2bazel repository map — "Versions are resolved, not remembered" in
docs/BAZEL-RULES.mdcompares one declaredrules_ccversion across three Bazel releases ↩1 ↩2 -
modCommand —graph,explain, andshow_repofor inspecting resolved module state, plus--include_builtinfor modules such as@bazel_tools↩1 ↩2 -
Command-Line Reference —
--check_direct_dependenciesvaluesoff,warning(default), anderror↩ -
MODULE.bazel files — directive surface for
module(),bazel_dep(), overrides,use_extension(), anduse_repo()↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 -
rules_applecrossrepository map — setup step 1 in the README and thesingle_version_overrideblocks inMODULE.bazel↩ -
Frequently asked questions — why
MODULE.bazelhas noload(), why version ranges/latest are unsupported, and whyuse_repo()is explicit ↩1 ↩2 ↩3 ↩4 -
Bazel Lockfile —
MODULE.bazel.lock,--lockfile_mode, and lockfile collaboration guidance ↩1 ↩2 -
Module extensions — extension implementation functions call repo rules to generate repos and can download through
module_ctx, so their downloads are decided in code ↩