Restricting toolchain registrations for bazel_deps

[fmeum]

In the Bzlmod BoF session at BazelCon 2026 and in other channels, the following challenges with Bzlmod have come up repeatedly:

1. Transitive bazel_deps can cause noticeable overhead (bytes downloaded from the network, time spent extracting archives, …) even when they aren't directly connected to the current build. For example, building a Bazel workspace with just an sh_binary currently fetches 65 repos, which requires 19 downloads of 32 MB in total, while only 9 repos and 4 downloads of 0.1 MB total are actually used in the build.
2. Transitive bazel_deps can register unwanted toolchains that result in surprising injection of behavior. For example, some BCR modules currently register custom Python interpreters.

There have been a few proposals that aim to address these issues, such as by introducing a feature system that supports optional deps or by requiring toolchain types to exhaustively list their toolchain implementations. A more drastic idea has been to disallow any toolchain registration outside the root module, perhaps gradually controlled via one or more flags.

I am currently exploring ways to make progress on 1. and 2. without adding new API to Bazel and without requiring changes to a considerable share of modules in the BCR. I'm looking for feedback on the following idea.

Limiting toolchain registrations to the module defining a toolchain type

Behind an incompatible flag, Bazel would ignore all toolchain registrations for a toolchain type defined in a repo A unless the registering module is one of

1. the root module;
2. the module whose repo is A;
3. the module defining a module extension that instantiates A.

It would also ignore (or even disallow) all registered non-dev execution platforms in non-root modules (there are none in the entire BCR).

This would address issue 1 for builds as the sources of all the extra downloads are that Bazel needs to resolve the patterns for all toolchain registrations in all modules since it doesn't know what types they will ultimately resolve to.

This would also address a good chunk of issue 2 as the only source for a lang toolchain beyond the root module would then be rules_lang's MODULE.bazel, which greatly narrows down the scope for inspection and (if necessary) patching. This also ensures that registration ordering across modules (which is deterministic, but difficult to keep stable as deps are added) can't affect the outcome of resolutions anymore.

With the exception of seven C++ toolchain and three other modules in the BCR whose users would have to start explicitly registering the toolchains they provide, a survey of all latest versions of all BCR modules found no other cases where intentional behavior would necessarily be broken. Six modules would have to release new versions to remain functional with this change, but users would not be impacted beyond having to update to them. A few modules would no longer leak their registrations, which appeared unintentional upon inspection, to consumers. rules_java, rules_cc and rules_python's toolchain types would move from bazel_tools into the respective modules, which is independently useful for the ongoing work to decouple the Bazel core from specific rulesets.

Since registrations that don't follow these rules are ignored and not an error, the only consequence can be that a certain toolchain is no longer registered or that the order of registrations changes across modules. Note that making this an error wouldn't actually be possible without reintroducing the eager fetching, but BCR CI exercises this path since it tests all modules as non-root modules.

Users with custom registries would also be affected by this change. If they rely on utility modules that bring in toolchains, those would now need to be registered with an explicit register_toolchains call in the root module. If more complex aggregation from transitive toolchains is needed, a module extension could collect and stamp out the toolchains so that a single wildcard pattern can match them.

Notes

1. When these restrictions turn out to be insufficient, we can still explore other proposals that involve new API.
2. By itself this proposal doesn't help reduce the footprint of bazel mod deps or bazel mod tidy, which forcibly evaluate all module extensions to ensure that the resulting lockfile is complete. This can cause a lot of fetches and requires further changes (e.g., the introduction of a default scope for the lockfile), but also benefits from more restricted toolchain registrations.
3. Modules can still permit other modules to declare toolchains for their types via module extensions (rules_multitool is an example that even dynamically generates toolchain types). Crucially, this would now require explicit opt-in by providing a dedicated extension interface.

[meteorcloudy]

Thanks for this proposal, sounds very convincing for me, but would love to see a prototype to test against our cared use cases (like with protobuf).

With the exception of seven C++ toolchain and three other modules in the BCR

Do you have a link to those modules?

rules_java, rules_cc and rules_python's toolchain types would move from bazel_tools into the respective modules

@Wyverald We should think about how to smoothly migrate them out of bazel_tools.

[fmeum]

Do you have a link to those modules?

emsdk, hermetic_cc_toolchain, portable_cc_toolchain, rules_haskell, rules_ml_toolchain, rules_wasm and wpilib_toolchains for C++. rules_nixpkgs_nodejs and
mboworks_bashtest (and toolchains_protoc, but that one is pretty much obsolete now with prebuilt protoc) are the non-C++ examples. rules_rs has already been updated, rules_multitool would need an update that I have in flight.

We should think about how to smoothly migrate them out of bazel_tools.

We can use bazel-contrib/bazel_features#165 to flip them over safely, with an alias pointing into the other direction (which flips after the feature is live). I have PRs for Python and Java, which I think should be fairly smooth after #32235.

[fmeum]

A prototype for the Bazel PR (<500 lines including tests): #32487
A matching BCR check to ensure that all new modules register toolchains for types they don't own with dev_dependency = True: bazelbuild/bazel-central-registry#11612

[fmeum]

A new bazel mod show_toolchains command that can be used for the BCR check as well as local debugging: #32581

[kayliespace]

Popping in to mention that "utility module that brings in toolchains" is a real concern to remember! This transition is feasible for us, but we do rely on this behavior and would need to migrate. However, the behavioral improvement is a huge net positive so I think we'd migrate as soon as able.

[fmeum]

Could you describe what the transition would look like for you? We could document best practices for it.

[kayliespace]

Absolutely. On our end, we'd start setting this flag per-repo, ideally using (in progress) LSC tooling to make the necessary MRs to individual repositories with an automated patch. (Folks without tools for this can ofc do the same thing but manually.)

So we'd introduce a new module extension as described in the proposal (I agree with that technical decision) and have each module individually register all required toolchains with wildcards.

This assumes:

• We get a compatibility flag for this functionality.
• We figure out enough of how to handle some of the limitations of module extensions to ensure toolchains are registered how we expect. (see rules_python for a possible problem case, its toolchain resolution seems weird to me and I don't fully understand it atm.)

[fmeum]

You can also take a look at rules_go. Is important to take into account how wildcard patterns are expanded. I would make sure to add docs about this.

[kayliespace]

It'd be awesome if this incompat flag can end up in a minor release of Bazel 9 or Bazel 10.

[katre]

This sounds good. I think most of the concerning cases are around modules that define CC toolchains, which will arguably be more clear and correct after this is implemented. My biggest concern is apple_support, which defines cc toolchains for local XCode installs in a @local_config_apple_cc_toolchains repo. This should be fixable by adding a module extension users can use, but is a breaking change and would need to be handled.

Speaking of changes to CC toolchains, I feel we should make the proposed change to move local CC toolchain detection into a separate module and out of @bazel_tools before implementing this, but make sure the new module works properly.

[fmeum]

We can special case apple_support in rules_cc to make this smooth. Cc @keith

C++ toolchain detection has already moved into rules_cc, only the toolchain type is left.

[keith]

since we're killing the macOS toolchain from rules_cc I think this is kinda fine. When the users flipped the breaking flag / updated to a new major bazel version they would have to add this dep / register_toolchains

[fmeum]

I'm still leaning towards registering it by default as the result would otherwise be unsymmetric: Linux and Windows would get a default C++ toolchain, macOS wouldn't.

[haberman]

Limiting register_toolchains() to the root module or the module defining the toolchain_type is definitely a step in the right direction. +1 from me.

If I'm understanding correctly, the main functional benefit of this proposal is that Bazel can assume that register_toolchains() in a non-root module does not need to be evaluated unless a toolchain_type defined in that module's repos is reachable from the currently requested set of targets. So, for example, a register_toolchains() in rules_rust does not need to be evaluated unless the build includes some kind of rust_*() rule that needs the Rust toolchain_type.

A few preliminary questions:

1. When do you anticipate that we would flip the incompatible flag, so the change takes effect by default? Bazel 11?
2. "Six modules would have to release new versions to remain functional with this change, but users would not be impacted beyond having to update to them." Can you give an example of the code changes that are required in these six modules?

Flag vs MODULE.bazel

My main feedback/request is: for users that will need to migrate anyway by explicitly registering their toolchain in the root module, can we recommend that they use the --extra_toolchains flag in .bazelrc instead of using register_toolchains() in MODULE.bazel?

The --extra_toolchains flag will always work, unlike register_toolchains() which, after this proposal, may silently do nothing. Using a flag instead of MODULE.bazel would give a clearer story for why it only works in the root module -- the root module effectively owns the configuration, which is why .bazelrc in non-root modules is ignored.

A potential long-term story that I think fits together nicely is that toolchains are eventually referenced either:

1. From an attribute on the toolchain type itself (for the "default" toolchain(s) defined in the type's own module)
2. From a flag in the .bazelrc of the top-level module.

That is the core proposition of my proposal Make Toolchain Resolution Local. This proposal overlaps in recognizing that two modules are "special" when it comes to toolchains: the module that defines the toolchain type and the root module.

Compared with "Make Toolchain Resolution Local"

I view this proposal as a more incremental version of Make Toolchain Resolution Local that captures some of the benefits while requiring fewer changes from users. In particular, it accomplishes these benefits from the other proposal:

• Per-Module Lazy Loading: This approach would give most (but not all) of the same lazy loading benefits. The only case where it falls short is if a module defines more than one toolchain type: we can't tell from the register_toolchains() call which toolchain type it is, so we're forced to eagerly evaluate all such calls in the module, even if they end up being for a toolchain type that isn't needed. This might not be as common in OSS Bazel land, since each "rules" repo is generally scoped to a single language, but in monorepos this is a much bigger deal, since the monorepo will often define dozens of toolchain types.

In the future we could consider trying to land Make Toolchain Resolution Local, which would be made easier if this proposal lands first. That would bring the following additional benefits:

• Explicit Dependency Edge: the "default" toolchain dependencies would become visible to bazel query, Kythe, or other build graph processing code without requiring much if any special-case code that knows about toolchains. The explicit dependency edge is easier to follow for readers of the code as well. Toolchain overrides from flags would still be visible to blaze cquery.
• Within Repo/Module Lazy Loading: In the case that a single module defines multiple toolchain types, and a given build reaches only some of them, we could precisely load only the toolchains for the type that is actually reached.
• Rule Owner Control: Rule owners that want more control over who provides a toolchain can opt into that, while still allowing full decoupling for rule owners who are happy with that.

[fmeum]

When do you anticipate that we would flip the incompatible flag, so the change takes effect by default? Bazel 11?

Bazel 11 for sure, the breakages are quite contained. If we think that this is a high priority to improve, Bazel 10 may still be an option. @Wyverald

Can you give an example of the code changes that are required in these six modules?

hermeticbuild/rules_rs#325 and bazel-contrib/rules_multitool#132 are the most interesting cases.

I'll respond to the rest later.

[fmeum]

... can we recommend that they use the --extra_toolchains flag in .bazelrc instead of using register_toolchains() in MODULE.bazel?

While I agree that we might handle toolchain registration differently if we started over today, I'm quite convinced that --extra_toolchains is worse:

• it is also ignored if the current project is not the root
• register_toolchains lives in the same file that also brings the toolchain repo into scope with use_repo
• transitions can reset --extra_toolchains
• its order of precedence is geared towards use in transitions and overrides
• .bazelrc has the general UX problem that it mixes configuration that goes into the build and low-level build system tweaking

we can't tell from the register_toolchains() call which toolchain type it is, so we're forced to eagerly evaluate all such calls in the module, even if they end up being for a toolchain type that isn't needed. This might not be as common in OSS Bazel land, since each "rules" repo is generally scoped to a single language, but in monorepos this is a much bigger deal, since the monorepo will often define dozens of toolchain types.

This may become relevant over time and we may want to consider solutions to this. An alternative would be to add an optional toolchain_types parameter to register_toolchains that enables the same kind of pruning. This would also help with your "Within Repo/Module Lazy Loading" point.

Rule Owner Control: Rule owners that want more control over who provides a toolchain can opt into that, while still allowing full decoupling for rule owners who are happy with that.

Isn't this already possible with the current proposal? Or are you saying that they should also have control over what the root module can do?

Explicit Dependency Edge: the "default" toolchain dependencies would become visible to bazel query, Kythe, or other build graph processing code without requiring much if any special-case code that knows about toolchains.

Wouldn't this give misleading results if a non-default toolchain ends up being chosen?

[haberman]

transitions can reset --extra_toolchains

Why is that necessarily a bad thing?

I can think of one answer to that: --extra_toolchains affects all toolchain types, and therefore has too big of a blast radius to be suitable for changing in the middle of a build. That's a fair point, and probably enough on its own for me to withdraw the suggestion that we ask that users migrate to it. In which case I am +1 on this proposal, without any requests for change.

That said, I'd be interested in finding a good forum to continue the discussion about future directions. I started typing responses to your other comments/questions, but both the length and scope of my replies would probably make more sense in a dedicated discussion.

[Wyverald]

I thought a bit more about the 'escape hatch' idea we discussed at today's SIG meeting. The basic idea: with this proposal, to resolve toolchains of type T, Bazel only looks at the toolchain registrations of the root module and the owner of T. As an escape hatch, a module M can declare that it needs to register toolchains of a 'foreign' type T even when it's not the root module, so that Bazel also considers it for T. This is an API that should be used sparingly.

I had a few ideas regarding the exact API, all of which are MODULE.bazel additions -- which would need to be backported, so we should try to decide soon. In the order of my preference:

1. bazel_dep(name="rules_cc", ..., register_for_toolchain_types=True) (param name TBD; other choices include use_toolchain_types, need_toolchain_types, claim_toolchain_types, etc)

   The idea being that M can have a dependency on rules_cc, and say "I will register toolchains of types found in rules_cc". So when Bazel looks at toolchains for type @rules_cc//cc:toolchain_type, M's registrations will be considered.

   This is a per-module escape hatch. It might seem too coarse, but it also doesn't require a new top-level API.

2. register_foreign_toolchain_types("@rules_cc//cc:toolchain_type") (directive name TBD; other choices are funnily enough same as above)

   The idea being that M can say "I will register some toolchains of these types, and Bazel needs to always consider them for these types".

   This is a per-toolchain-type escape hatch. The naming is really awkward, and sometimes it might not be feasible to enumerate all toolchain types you want to register for.

3. register_toolchains(..., toolchain_types=["@rules_cc//cc:toolchain_type"])

   This revives the old proposed API by inlining the toolchain type at registration time.

   While it seems really apt, there are several downsides: 1) toolchain_types is somewhat deceptively an additive API here: if you omit it, it means "look at these registrations for a toolchain type I own"; but if you specify some types here, it means "also look at these registrations for these types". 2) The types inlined here might not match the actual declared types in the toolchain targets, which might lead to silently dropped registrations or sudden errors when someone happens to build a target of a certain type. 3) age-old question: toolchain targets are <toolchain type, constraints, toolchain binary> tuples. If you inline the toolchain type, why not the constraints? Why not the toolchain binary label?

[meteorcloudy]

Can we just do register_toolchains(..., always = True)? If always = True, the definition of the registered toolchains are always fetched and considered in resolution. Otherwise, it's only fetched when some targets request toolchains with type defined in this module. By default, it will be false.

[fmeum]

As an escape hatch, a module M can declare that it needs to register toolchains of a 'foreign' type T even when it's not the root module, so that Bazel also considers it for T. This is an API that should be used sparingly.

It makes sense to think this case through, but I wonder what use case there is for an escape hatch without the cooperation of T's owning module? We've so far encountered the following situations:

• rules_cc split out its macOS toolchain into apple_support: We probably want every Bazel build to have a default C++ toolchain registered. rules_cc can provide a module extension limited to apple_support with which the latter can register its toolchain.
• aspect_rules_* -> rules_* migration: As long as aspect_rules_* aliases its toolchain types to rules_*, it doesn't even have to register any toolchains anymore. Its module extensions can serialize their tags to JSON that rules_* corresponding extension reads.

We would only need this escape hatch if we wanted to allow a module to keep registering a toolchain without the permission of the owning module, which somewhat breaks desired property 2.

Given that, if we want one, I would go with the third option. This one is useful also for monorepos as it permits perfectly lazy loading even of different registrations within the same module, realizing all the gains of Josh's proposal in this area. 1) seems fine to me ("I provided more information and thus gain more support"). 2) is always going to be an issue with manual tagging like this, but we could have an opt-in diagnostic mode that catches this. 3) because the type is the one thing lazy discovery needs to know to prune a good chunk of non-candidates. The toolchain binary label only ever makes sense to know post-selection. The constraints are a middle ground and I could see a future where we want to prune on them more aggressively.

In summary, I'm not sure we need the escape hatch now, but if we do decide to add it, it would also benefit other cases.

[haberman]

Anytime we allow arbitrary modules to register arbitrary toolchains, we run into an ordering problem: toolchain registration is order-dependent, and there's no predictable way to reason about how the toolchain registrations from different modules will interact.

It also violates a desirable property of a module system: you should be able to add a dependency on a module without worrying that it will have unpredictable side effects. Imagine that someone proposed that MODULE.bazel should be able to set any flag, with a syntax like set_flag("--spawn_strategy=local"). If we allowed this, users would run a risk every time they add a dependency on a new module that it might change unrelated behaviors in an undesirable way.

Toolchain registration is the equivalent of pre-main static initialization in C++ or static blocks in Java. It runs arbitrary code and side effects in an unpredictable order before any of the main code for the build runs. It is not a good model for mutating shared global state like the toolchain registry.

This one is useful also for monorepos as it permits perfectly lazy loading even of different registrations within the same module, realizing all the gains of Josh's proposal in this area.

Precise lazy loading is only one of the gains I was seeking for monorepos. There are others that I also consider important that would not be solved by option (3) above:

1. Visible to bazel query, Kythe, and readers of the code: right now bazel query bottoms out at the toolchain type, because there is no dependency edge from the toolchain type to the default set of toolchains. If default toolchains were regular dependency edges of the toolchain type, regular graph traversal would find them. Readers of the code would be able to click through from the toolchain type to the default toolchain definitions.
2. Allows default toolchains to be written as normal dependency edges in normal BUILD files: At the point that we're asking users to write register_toolchains([<toolchain>], toolchain_types=[<type>]), what we have is essentially a regular dependency edge from <type> to <toolchain> that we force to be in the global workspace file for no reason. In a monorepo, that file becomes scary to modify (the equivalent file inside Google has a big warning banner with onerous conditions for modifying it) because every line has repo-wide blast radius, and every team adding a new toolchain has to touch it. If that file contained multiple registrations for the same toolchain, it would not be obvious because they could be spread across the file. A normal attribute on toolchain_type(default_toolchains=[]) would solve all of these problems.

Since it's relevant to the points above, I'll also answer one of the questions you posed above:

Wouldn't [bazel query] give misleading results if a non-default toolchain ends up being chosen?

Yes, but that is identical to how select() and label_flag(build_setting_default = ...) work in bazel query today. The graph is only fully configuration-accurate under cquery—the unconfigured query graph is an over-approximation / default-configuration view (and flags can inject new dependencies that don't appear in query). Showing the default toolchain edge in query is still much more informative than today, where query sees toolchain_type as a dead end with zero edges to any toolchain implementation even when the default toolchain is used.

[davido]

I tried the #32487 prototype against a real non-LTS JDK catalog
(davido/jdk_catalog) and a Java
consumer (Gerrit) on macOS x86_64. Two observations — a catalog-author packaging
pattern, and the pre-migration failure sequence for anyone testing now.

A catalog can reduce the consumer change to one root registration.

The catalog previously registered runtime toolchains from generated per-JDK
repositories. A packaging change now defines its compile (via
default_java_toolchain), runtime and bootstrap toolchain registration targets in
one package, so the consumer setup becomes a single
register_toolchains("@jdk_catalog//toolchains:all")
(catalog,
Gerrit registration).

The same registration is accepted on Bazel 9.3.0 and on the prototype. On 9.3.0,
keeping the catalog's existing self-registration alongside the root one produced
no duplicate-registration diagnostic in the tested consumer, and under the flag
the root registration is needed.

This looks like a useful concrete example for the migration docs — authors can
expose a package-wide pattern so consumers need not duplicate the generated
repository list. Open question: the proposed BCR check has a per-PR skip — is that
the intended bridge for catalogs that temporarily retain non-dev self-registration
for existing consumers, or is dev_dependency = True expected from the first
release?

The pre-migration failure sequence (stock rules_java), for testing guidance.

At prototype 0c3cc4c0e8 with stock rules_java 9.9.0 and the flag enabled, a plain
java_binary first fails Java toolchain resolution; supplying root Java
registrations then exposes, on this setup, a C++ toolchain failure while analyzing
@bazel_tools//tools/jdk:proguard_allowlister. Both stages build with the same
prototype build when the flag is disabled
(reproducer and failure output).

The native helper is an analysis dependency of the selected stock Java toolchain
(not a Proguard run), so a java_library reaches it too. This depends on the
selected Java toolchain configuration — selecting a prebuilt allowlister avoids
this helper's C++ dependency. Importing and root-registering apple_support's
generated host C++ toolchains restores the binary on this macOS setup;
root-registering it satisfies the ownership rule for this case.

If a non-root integration fixture would help the Java/C++ type migrations, this
repro exercises the proguard_allowlister C++ dependency and the macOS host
toolchain provider.

[fmeum]

The per-PR skip will probably stay to not block releases, but we would always prefer folks to migrate now. We'll also find a way to register apple_support by default.