0.3.7 Aliases - Bazel Book

alias() is the rule for giving an existing target another label. It does not create a second implementation. It creates a stable handle that other packages can depend on even if the real target later moves, gets renamed, or already sits behind a long label.¹

alias(
    name = "my_lib",
    actual = "//path/to/real:lib",
)

In the example above, other targets can depend on //path/to:my_lib instead of //path/to/real:lib.¹ That is the core mental model for alias(): the visible label and the underlying target are not the same thing, even though they lead to the same implementation.¹

The Two Attributes To Notice

The syntax is small. name gives the alias its own label in the current package, and actual points at the target it redirects to.¹ The same source notes that an alias can also declare its own visibility, so the access-control rules from 0.2.4 Visibility still matter when you expose a target under an alternate name.¹

Why This Rule Exists

The value of alias() is indirection. If a package wants one stable public label while the real implementation target changes over time, an alias keeps consumers decoupled from that internal churn.¹ That is why it helps with renames, refactors, and package APIs that want a cleaner public entry point than the underlying target path.¹

This is also why the concept belongs next to BUILD-file reading rather than next to file selection — the separate file-collection case is covered in 0.3.6 filegroup Rule.¹

At a smaller scale, Aspect's training material points out one ergonomic use: if a package does not naturally have an eponymous default target, alias() can create one.² That connects back to the shorthand rules in 0.2.2 Syntactic Sugar & Relative Labels, but the mechanism is the same: one label stands in for another target.²

extra

A Legacy Pattern You May Still See

Bazel's Bzlmod migration guide uses alias() as a replacement for old bind() entries from WORKSPACE.³ Instead of keeping dependents on //external:openssl, the guide shows defining a normal alias in a regular package and moving callers to that package-local label.³

alias(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

key takeaway

An alias is a stable label that points at an existing target. When you see alias(), read it as a small indirection layer in the target graph: consumers depend on the alias name, and the alias forwards them to the real thing. That makes renames, refactors, and cleaner package interfaces cheaper without changing the underlying implementation.¹

Ultimate Monorepo and Bazel for Building Apps at Scale — alias as redirect/pointer, name and actual, optional visibility, and stable-name/refactor use cases ↩¹ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹
Bazel Training 101 (Part 9): Packages, Rules, Targets, and Labels — using alias() to create a package default target when no natural eponymous target exists ↩¹ ↩²
Bzlmod Migration Guide — replacing legacy bind() entries with a normal alias() target in a regular package ↩¹ ↩²

Aliases

The Two Attributes To Notice

Why This Rule Exists

A Legacy Pattern You May Still See

Footnotes