0.2.4 Visibility

Visibility is Bazel's dependency-policy mechanism for the build graph. It determines which targets can reference a given target's label in attributes like deps¹. It does not prevent someone from reading source files or provide runtime access control. When target A depends on target B, Bazel checks whether B's visibility grants access to A's package. If not, the build fails during the analysis phase, before any compilation happens¹.

This is how you enforce architectural boundaries mechanically. A library can expose its public API to consumers across the repository while keeping internal helpers invisible. Bazel enforces those boundaries at build time rather than by convention.

Visibility Specifications

Every rule target has a visibility attribute that accepts a list of package specifications². The first four forms use special placeholder syntax and do not correspond to real targets in the build graph:

• "//visibility:public" — accessible from all packages.
• "//visibility:private" — accessible only within the declaring package.
• "//foo/bar:__pkg__" — accessible to targets in //foo/bar, but not its subpackages.
• "//foo/bar:__subpackages__" — accessible to //foo/bar and all packages nested under it, at any depth.

The fifth form is an ordinary label pointing at a real package_group target:

• "//some_pkg:my_package_group" — accessible to all packages in the named package_group (see 0.2.5 package_group).

Note the asymmetry between __pkg__ and __subpackages__. Granting visibility to //tests:__pkg__ allows targets in //tests/BUILD.bazel to depend on you, but targets in //tests/integration/BUILD.bazel are blocked². The __subpackages__ form covers the entire subtree.

Multiple specifications combine into a union. A target visible to //src/app:__subpackages__ and //tests:__pkg__ can be used anywhere under //src/app/... and in //tests, but not in //tests/integration:

cc_library(
    name = "internal_utils",
    srcs = ["utils.cc"],
    visibility = [
        "//src/app:__subpackages__",
        "//tests:__pkg__",
    ],
)

When granting access to another team's project, prefer __subpackages__ over __pkg__³. Projects evolve and add subdirectories, so __pkg__ forces a visibility update every time that happens.

Defaults

When a target omits the visibility attribute, Bazel applies the package's default_visibility if one is set via package(). Otherwise, the target is private and visible only within its own package⁴. The package() function is covered in 0.2.6 package() Function.

Generated file targets, which are outputs produced by rules, inherit the visibility of the rule that creates them⁴. A java_binary visible to //friend:__pkg__ makes its implicit outputs (like _deploy.jar) visible to //friend as well.

What a Visibility Violation Looks Like

Visibility errors surface during analysis, before compilation, linking, or any real work¹. Bazel reports which target is inaccessible and from where:

java_binary(
    name = "server",
    srcs = ["Main.java"],
    main_class = "app.Main",
    deps = ["//lib:internal"],
)

ERROR: .../app/BUILD.bazel:3:12: in java_binary rule //app:server:
    Visibility error:
    target '//lib:internal' is not visible from
    target '//app:server'
    Recommendation: modify the visibility declaration if you think
    the dependency is legitimate. For more info see
    https://bazel.build/concepts/visibility

Reproduce this error

The fix is either to widen the target's visibility or to restructure the dependency. Visibility errors stop developers from reaching into implementation details that were never intended as stable API. Visibility becomes a key tool for enforcing dependency and API policy as the codebase scales (H.5.2 Dependency Boundaries). It is not a confidentiality or runtime-authorization mechanism. H.9.2 Trust Boundaries shows where build-graph policy ends and security controls must begin.

For source-file visibility rather than target visibility, compare the private and package-scoped declarations in data/BUILD.bazel.