3.1.3 Repo Mapping

When you write @rules_cc//cc:defs.bzl or @maven//:org_junit_junit, the string after @ is not necessarily the directory name under $(bazel info output_base)/external/. Bazel keeps an internal canonical name for every repository and exposes apparent names that depend on which repository's BUILD file you are standing in. That per-repo table—apparent name → canonical name—is repository mapping. It is what makes strict direct-dependency visibility work under Bzlmod, why use_repo() matters for extensions, and why migration guides beg you not to hard-code paths derived from canonical names.^1,2

Two names, one tree

Inside a workspace, each external repository has exactly one canonical name. A target in that repo is always reachable with a label of the form @@<canonical>//package:target (double @).¹

The apparent name is the nickname a repo is allowed to use in a given context: the repo you are loading from keeps a mapping from apparent names to canonical names, so @mike//... in module alice might resolve the same tree as @mickey//... in module bob. In ordinary BUILD files you write single-@ labels. Bazel resolves them using the current repo's mapping.¹

The main repository—the checkout you run Bazel in—has the empty string as its canonical name.¹ Everything in 3.1.1 Bzlmod (MODULE.bazel) about “after resolution, modules become repositories” is really about Bazel synthesizing those canonical repos, then wiring apparent names so your MODULE.bazel dependencies look stable in labels.

How Bzlmod wires apparent names

For a repository that represents another module, the apparent name seen by direct dependents defaults to the dependency's module name, unless bazel_dep(..., repo_name = ...) chooses a different alias. That default is the core of strict deps: a module is not supposed to see transitive module repos just because they exist somewhere deeper in the graph—you only get names for what you declared.²

Module extensions add repos after module resolution. The extension's documentation is the contract for which repo names it creates. use_repo(extension_proxy, "maven") is what brings a generated repo into your module’s visible scope so labels like @maven//... resolve at all.³ Until that import exists, the repo may be created for another consumer but not mapped for you—this is the behavioral link back to 3.1.2 Using Extensions.

The maintainer-workspace MODULE.bazel shows that import step in context: a repo-local extension is bound, a tag is declared, and use_repo() makes the generated @release_policy repository apparent to the main module.

Canonical names are not a public path API

The canonical name format is not an API and can change. You should not bake it into strip_prefix strings, shell scripts, or deployment steps.²

Supported alternatives include:

• In Starlark, construct a Label from the apparent repo label and read Label.repo_name when you need Bazel's canonical string.²
• For runfiles, prefer $(rlocationpath …) or a language runfiles library so runtime code does not depend on a particular canonical spelling. Use the apparent repository name in the logical rlocation path, then let the library translate it for the current execution context.^2,4,5 The repo-mapping-runfiles target shows the runfiles-safe shape: args = ["$(rlocationpath @aux_data//:value.txt)"] plus data = ["@aux_data//:value.txt"], with the binary resolving the token through the standard bash runfiles library at runtime.
• For tools outside Bazel (IDEs, language servers), bazel mod dump_repo_mapping exists to dump apparent→canonical mappings for a chosen base context.²

The practical failure mode—especially after enabling Bzlmod—is packaging or scripts that matched the old external/<apparent-name>_* layout. Paths on disk live under the output base's external/ directory by canonical name, so anything that assumed the apparent string equals the directory segment silently drifts.^1,6 The assumes_canonical_path.sh sibling script in the same snippet documents that anti-pattern in one place — it only prints the warning rather than actually reading the guessed path, since the canonical layout is explicitly not an API and would change under your feet.

Vendor mode exposes the same naming split in a configuration file: VENDOR.bazel directives use canonical repo names, not everyday apparent labels.

Debugging and migration

When a label @foo//... "should" exist but resolution fails, first ask which repo is the context for resolving @foo: in a BUILD file that is the repo containing the file, while labels on the Bazel command line are treated as if they come from the main repo.⁷ Then work outward from intent: confirm the module or extension actually provides the repo, confirm your module declares it (bazel_dep, use_repo, or use_repo_rule), then inspect how Bazel named it. bazel mod show_repo accepts both apparent (@name) and canonical (@@name) forms. Apparent names are interpreted relative to --base_module (default <root>).^8,7

Brownfield moves where WORKSPACE chose arbitrary http_archive(name = …) values are exactly where naming surprises cluster: Bzlmod's canonical scheme is different, and strict visibility may hide repos you used to reach accidentally. For the broader migration track, see M1 WORKSPACE → Bzlmod. The two most relevant follow-ups here are M1.5 Repo Name Handling in Rules and M1.6 Runfiles Path Portability.^4,6