3.4.3 Buildozer

Buildozer is a command-line tool that rewrites BUILD files — the anatomy from 0.3.1 Anatomy of a BUILD File — using structured commands instead of regex or manual edits. It parses the file into its syntax tree, applies the change, and writes the file back — preserving formatting and comments — all without starting a Bazel server or loading the graph from 2.2.1 Loading, Analysis & Execution.¹ That purely syntactic pass is why it scales: the same command that changes one target works unchanged across thousands of BUILD files, and the edit completes in milliseconds per file.

The other thing to know up front is that buildozer is not only something you run by hand. Many tools in the Bazel ecosystem — bazel mod graph under Bzlmod,² strict-deps diagnostics,³ Aspect CLI plugins,⁴ FawltyDeps⁵ — print ready-to-paste buildozer commands as their "fix" output. Learning buildozer's syntax is therefore also learning how to read the remediation advice Bazel and its surrounding tooling already emit.

Anatomy of a buildozer invocation

The general form is one or more commands followed by one or more targets:¹

buildozer [OPTIONS] 'command arg...' [label]...

Each command is a single positional argument, so commands are quoted to keep spaces intact. Multiple commands and multiple labels can appear in one invocation. Buildozer applies every command to every target and processes files in parallel.¹ A minimal example — adding a dependency to a target:

buildozer 'add deps //lib:foo' //my:target

Buildozer accepts the same label grammar as Bazel, plus a few extras that only make sense at the syntax level:¹

Target form	What it means
//pkg:name	One specific target
//pkg:__pkg__	The package() call (for package-level defaults)
//pkg:*	Every rule in the BUILD file
//pkg/...:*	Every rule in every BUILD file under pkg/
//pkg:%java_library	Every java_library in the BUILD file
//pkg:%123	The rule that starts at line 123

__pkg__ and %rule_kind have no meaning to Bazel itself — buildozer looks at unevaluated BUILD files, so it talks about package() declarations and rule kinds directly, not about expanded targets. That is also why bazel query and buildozer occasionally disagree about what exists in a package: buildozer sees what's written, query sees what macros produce.¹

The commands a maintainer reaches for

Buildozer ships a small vocabulary of edit commands.¹ A few carry almost all the day-to-day weight:

# Add //base to deps of //pkg:rule and //pkg:rule2
buildozer 'add deps //base' //pkg:rule //pkg:rule2

# Remove a dep from every cc_library in a package
buildozer 'remove deps //legacy:util' //pkg:%cc_library

# Replace one dep with another (useful for migrations)
buildozer 'replace deps //pkg_v1 //pkg_v2' //pkg:rule

# Rename an attribute across all rules in a file
buildozer 'rename old_attr new_attr' '//pkg:*'

# Set package-wide defaults
buildozer 'set default_visibility //visibility:public' //pkg:__pkg__

There are also read-only commands. print is the one that matters most day-to-day — it lets you inspect BUILD files without running a Bazel query:¹

# List all cc_library names in //base
buildozer 'print name' '//base:%cc_library'

# Print the full definition of one target, including comments
buildozer 'print rule' //base:heapcheck

Because print works on the syntax tree, it returns instantly and does not trigger fetching, loading, or analysis — exactly the property to exploit whenever you need to inspect BUILD contents at developer speed.⁶

Batching: command files and query | xargs buildozer

For a handful of targets you pass commands on the command line. For mass refactoring you switch to a command file fed through -f, with one |-separated line per edit:¹

# /tmp/cmds
add deps //base //strings|//buildtools/buildozer:foo
add deps :foo|//buildtools/buildozer

buildozer -f /tmp/cmds

The build-maintenance plan helper is the reviewable shape of this idea: it prints the add deps, replace deps, remove deps, and print rule lines a maintainer would inspect — and optionally drop into a -f file — without invoking buildozer itself.

For the focused target-form exercise, the buildozer-command-file snippet generates a command file and asserts that it contains the single-target, kind-filtered, package-wide, and package pseudo-target forms discussed above.

The companion pattern chains bazel query into buildozer. Query finds the targets that need changes — by label, rule kind, rdeps, or any other predicate from 5.2.1 bazel query — Static Graph Analysis — and xargs feeds them as explicit buildozer arguments. This is the idiom 3.7.2 Workflows Outside Bazel already recommends for avoiding collector targets, and it works just as well for edits:

bazel query 'kind(java_library, //foo/...)' \
  | xargs buildozer 'remove tags manual'

The same pairing is useful during validation: buildozer is the right tool when you need to query BUILD files statically — for example, to confirm that no target under a directory still has a given attribute.⁷ Compared to running bazel query against every commit, a buildozer print pass has no analysis overhead and no external-fetch side effects.

MODULE.bazel: the special commands

Buildozer also understands the Bzlmod root file from 3.1.1 Bzlmod (MODULE.bazel), with a dedicated set of commands that target top-level use_extension variables:¹

• use_repo_add <var> <repo>... — ensure the listed repos are imported via use_repo() for the extension bound to <var>.
• use_repo_remove <var> <repo>... — ensure the listed repos are not imported.

This matters because the extensions covered in 3.1.2 Using Extensions can return an extension_metadata object that reports which repos the root module should actually import. When they do, bazel mod graph prints a buildozer command that reconciles your use_repo() with what the extension produced. Running it fixes up MODULE.bazel without hand-editing.² This is the expected workflow for ruleset authors: ship an extension_metadata return from your extension, and let buildozer be the users' fixup tool.²

The emit-and-apply pattern

The more surprising thing is how often other tools are the ones printing buildozer commands at you. A few concrete examples:

• Strict deps under Bzlmod. When rules_scala's strict-dependency check reports a missing direct dep, its error message ends with a runnable buildozer line. Under Bzlmod, that line uses the canonical repo name from 3.1.3 Repo Mapping — buildozer 'add deps @@+scala_deps+io_bazel_rules_scala_guava...' //some:target — so the user can paste and run it without worrying about apparent-name resolution.³
• Aspect CLI fix-visibility (3.5.4 Aspect CLI Extensibility). Subscribes to the Build Event Protocol, detects is not visible from target errors, and either applies the buildozer edit interactively or prints the equivalent command when running on CI.⁴
• FawltyDeps (Python). Published as rules_fawltydeps, it runs as an aspect over py_library targets via bazel build and emits one buildozer command per finding. The recommended mass-fix idiom is to grep those lines out of the build output and pipe them to the shell — bazel build ... | grep buildozer | bash.⁵
• Preventing production-code experiments. A concrete pattern uses buildozer to mark whole experimental subtrees as testonly from 1.2.4 testonly Attribute, then prints those same idempotent commands back to the developer as the "how to fix a red build" instructions:⁸

buildozer 'set default_testonly True' //experimental/...:__pkg__
buildozer 'comment code\ in\ experimental\ may\ only\ be\ used\ for\ testing' \
  //experimental/...:__pkg__

The common thread is that buildozer commands are portable remediation artifacts. They survive logs, CI output, and chat copy-paste. A developer does not need to understand the tool that produced them to apply the fix. This is also why breaking string values across lines is discouraged: doing so defeats buildozer's parser and code-search tooling, which would otherwise be able to find and update those values mechanically.⁹

The build-maintenance buildozer plan helper keeps that emit-then-review shape visible in a Level 3 example: it prints the add deps / replace deps / remove deps / print rule lines a maintainer would inspect before running buildozer, without applying any edit on its own.

The smaller buildozer-command-file assertion pins the same idea as a verification snippet: generate the command file first, then inspect the commands before any edit is applied.

Exit codes for CI

Buildozer's exit codes are designed to distinguish "nothing needed changing" from "change failed" — useful when wiring buildozer into presubmit checks or automation scripts:¹

Code	Meaning
0	Success. Changes were made, or only read-only commands ran
1	Usage error (bad arguments)
2	At least one command failed
3	Success. No changes were needed

A script that treats "3 means nothing to do" differently from "0 means something was fixed" can, for example, decide whether to open a pull request with the resulting diff or just exit quietly.

Distribution inside a repo

Most teams do not want each developer to run go install to get buildozer. The standard answer in modern setups is to manage it like any other hermetic tool: rules_multitool ships a tools/buildozer:buildozer target via a JSON lockfile, and bazel_env.bzl with direnv can add that binary to PATH automatically so buildozer works in a plain terminal.¹⁰ The detail is covered in 3.5.3 Developer Tool Management. The only thing to note here is that the article's examples assume buildozer is available under some consistent name, whether that is a bazel run @buildozer, a tools/buildozer wrapper, or a direnv-injected binary.