4.10.7 Extension Repository Manipulation

inject_repo() and override_repo() are root-module escape hatches for a module extension's repository namespace. They do not change which Bazel modules participate in version resolution. They change which already-visible repository an extension-generated repository name points to, or which additional repository an extension can see while it runs.¹ Reach for them when the problem is inside an extension's repo set, after the normal Bzlmod tools from 3.1.1 Bzlmod (MODULE.bazel) are too coarse.

The Scope They Modify

A module extension creates repositories in its own namespace. Repositories generated by the same extension can see each other by the names used in the repository rule calls. A module sees extension-generated repositories only after importing them with use_repo(), alongside other repositories introduced directly in its MODULE.bazel file.² That namespace boundary is why these APIs exist: the root module sometimes has a repository that an extension should use, but the extension would otherwise generate a different one or not see it at all.

Both functions take the extension proxy returned by use_extension(). They are root-module-only controls. If the current module is not the root module, or if --ignore_dev_dependency is enabled, the API reference says they are ignored.³

toolchains = use_extension("@rules_java//java:extension.bzl", "toolchains")

override_repo(toolchains, remote_java_tools = "my_java_tools")

In that shape, the key is the repository name in the extension's namespace, and the value is a repository visible to the current module. The positional form is shorthand for same-name replacement or injection. The keyword form lets the root module map different names.³

Override When the Extension Already Creates the Repo

Use override_repo() when the extension already defines a repository and the root module wants a different implementation for that name.³ The official module-extension guide shows this with rules_java: the root module first creates a local repository named my_java_tools, then overrides the extension's remote_java_tools repository with that vendored copy.⁴

This is narrower than local_path_override() or single_version_override(). A module override replaces a Bazel module before extension evaluation. override_repo() replaces one repository produced by one extension usage. That makes it a good debugging or vendoring tool when the ruleset's extension is mostly right, but one generated repository needs to point somewhere else.

Inject When the Extension Needs One More Repo

Use inject_repo() when the extension does not already create the repository, but its generated repositories need that repository in their visible scope.³ The official guide's Gazelle example patches a Go dependency to depend on @zlib, then injects the root module's zlib repository into the go_deps extension scope so the patched generated BUILD file can resolve that label.⁵

That distinction matters in migrations. override_repo() is the no-patch choice when replacing a same-named repository, and inject_repo() is the choice when a patch introduces a new repository reference that the dependency's extension must be able to see.⁶ In both cases, the point is to reuse an existing module extension instead of forking it or writing a custom extension just to expose one vendored dependency.

Name the Boundary Deliberately

These APIs are about apparent repository names, not canonical repository strings. Bazel's documentation says extension-generated repositories have canonical names derived from module and extension identity, but that canonical format is not an API.² Treat the extension's documented generated repo names as the contract, and keep the naming rules from 4.10.5 Repo Name Handling in mind when passing labels across module and extension boundaries.

If a repository name is not a valid Starlark identifier, pass a literal dict through **kwargs, for example:

override_repo(extension_proxy, **{"foo.2": "local_foo"})
inject_repo(extension_proxy, **{"foo.2": "local_foo"})

The API reference documents this form for both functions.³ It is rare, but it prevents the workaround from changing the repo name just to fit Starlark keyword syntax.

When Not to Use It

Do not use extension repository manipulation as a general dependency-policy layer. If the thing you need to replace is a Bazel module from a registry, use the ordinary root-module overrides from 3.1.1 Bzlmod (MODULE.bazel). If the extension author should expose a stable configuration tag, fix the extension API instead of forcing every root module to patch around it. If the repository is a toolchain or SDK implementation, this can be a useful local escape hatch, but the long-term published shape belongs with the toolchainization and setup surface in 4.11.2 Toolchainization.