3.4.5 Managing unused_deps

Extra deps on a target are not free. Every declared edge widens the set of actions an input change can invalidate, expands the per-action input set so cache hit rates drop and invalidation broadens, and makes the target graph harder to reason about — exactly the failure mode catalogued from the diagnostic side in 2.1.4 Common Dependency Issues. The way a maintainer keeps that drift under control is by pairing strict enforcement on the "missing deps" side with periodic pruning on the "unused deps" side, and letting tooling drive the edits instead of hand-audit.

At Stripe, engineers were waiting for Bazel the equivalent of 150 engineer-hours per day, and the investigation traced the cost back to BUILD files that had drifted — a single new payment service had accumulated 1,400 Java library dependencies because people added dependencies until the code compiled and moved on.¹ That is the failure the unused_deps workflow is designed to correct.

What unused_deps actually does

The canonical tool is unused_deps from bazelbuild/buildtools, the same repo that ships buildifier and buildozer. It is a Go binary, it takes a space-separated list of Bazel labels (with :all and ... target-pattern support), it is scoped to java_library rules, and it prints buildozer commands for the pruning it suggests rather than editing BUILD files in place.² Upstream documents go install github.com/bazelbuild/buildtools/unused_deps@latest as a convenient evaluation path. A shared repository or CI job should replace latest with a reviewed buildtools tag or commit and expose that pinned binary through 3.5.3 Developer Tool Management. Applying the results is therefore a versioned, reviewable diff, not a blind rewrite.

The buildtools repository map keeps the public unused_deps workflow next to the buildozer command contract, which is the shortest upstream route for checking both halves of that emit-then-review workflow.

unused_deps //... > prune.sh
# review prune.sh
bash prune.sh

The reason the tool is Java-specific is the same reason it gives trustworthy answers when it does work: it piggybacks on the Java compiler. The three-stage pattern is the clearest form of the idea — a Bazel graph pulled with bazel query --output proto, a Java source graph collected by a javac plugin that records imported and exported symbols, and a comparison step where edges present in the Bazel graph but absent from the source graph are flagged as unused.¹ That compile-time anchor is what separates a dependency that looks unused from one the compiler never resolved a symbol through.

Why a clean-looking tool gets noisy in practice

The reason unused_deps surprises people is that "used at compile time" and "declared in deps" are not the same set. Generated code, annotation processors like Dagger, and reflective runtime-only dependencies all show up as unused from a compile-time view even though removing them breaks the build at a later stage — run the upstream tool against such code and it produces a flood of errors, after which Bazel immediately suggests re-adding many of the dependencies it just deleted.¹

Macros around Java targets make the problem worse. A wrapper macro layered on top of java_export can break unused_deps and buildozer edits together, because the automated tooling can no longer see the real underlying rule it is meant to rewrite.³ This is the practical cost of abstraction layers on top of the native Java rules: the more the BUILD shape diverges from plain java_library, the less the upstream hygiene tooling applies.

Treat it as the other half of strict deps

unused_deps only makes sense when paired with --strict_java_deps. The flag controls whether javac refuses compilation when a source file references a type from a jar that is not part of the current target's direct dependencies. The accepted values are off, warn, error, strict, and the default (which behaves like strict).⁴ With it on, Bazel emits a [strict] error that names the missing target and suggests a shell command — in practice a buildozer 'add deps …' line — that automatically inserts the missing direct dependency.

Strict deps and unused_deps bracket the same hygiene problem from opposite sides. Strict deps stops you from relying on a transitive edge you never declared. unused_deps removes declared edges you no longer rely on. Strict transitive dependencies were rolled out across Google's codebase explicitly so that engineers could remove deps without fear of breaking distant targets, and pruning is the natural companion to that mode.⁵

On earlier Bazel versions, maintainers already treated unused_deps as an on-demand "remove unused deps → apply" step run before push rather than a blocking lint, because the compile-time-only view is too noisy to gate every edit on.⁶ The guidance has aged well: run it at specific moments, not every CI build.

The pattern beyond Java

The same "Bazel graph vs source graph, emit buildozer" shape recurs across languages, just with different analysers.⁷

• Python. rules_fawltydeps runs FawltyDeps as an aspect (see 4.8 Aspects) over py_library / PyInfo providers, compares declared deps with the imports it observes in source, and emits buildozer commands for fixes — with --strict_java_deps-like suggestions for missing packages and cached results because the analysis is executed through Bazel itself.⁸ Language-specific setup belongs in L3 Python.
• JVM ecosystems. bazel-deps is the JVM equivalent, and the broader classpath governance story — duplicate classes, unwanted transitives — sits under L1 Java & Kotlin (JVM).
• C++ and similar. Tools like depend_on_what_you_use and bazel_iwyu fill the same role for C/C++ by scanning headers, and they belong to the same state-of-the-art set as FawltyDeps and bazel-deps for keeping deps honest.⁷

None of these are fully safe to automate. Dep-metadata freshness generally cannot be automated end to end, because edge cases and occasional false positives are unavoidable.⁷ That is why every one of these tools emits buildozer commands for a human to review instead of editing BUILD files in place.

A workflow that survives the false positives

A few working patterns show up repeatedly in practice:

• Scope to targets you understand. Do not run unused_deps repo-wide unless you can judge which services carry runtime-only dependencies. A workable rollout publishes the tool internally and lets teams opt in. Where teams actually run it, reductions of up to 35 % in runtime deps are achievable.¹
• Make the diff reviewable. The tool's output is a shell script of buildozer commands. Keep that separation: run the tool, inspect the diff, apply only the commands you trust, commit the rest for follow-up. buildozer is covered in more detail in 3.4.3 Buildozer. The build-maintenance app/BUILD.bazel keeps a deliberately stale //unused:unused_helper edge so the buildozer plan helper can emit the matching remove deps line — the same emit-then-review shape the real unused_deps tool produces, even though the example does not run unused_deps itself. The buildozer-command-file snippet narrows that pattern to one generated command file so the review step is easy to inspect.
• Pair with --strict_java_deps rather than relying on it alone. Strict deps alone will eventually accumulate deps entries that have outlived their imports. Periodic unused_deps passes keep that list honest.^4,5
• Respect runtime and reflective edges. When a genuinely runtime-only dep shows up as "unused", the fix is documentation or a test that exercises it, not a blanket removal. This is exactly why hygiene belongs on-demand before push rather than in an interactive lint.⁶
• Do not confuse it with Gazelle. 3.4.2 Gazelle (BUILD File Generation) generates deps from source imports for supported languages. unused_deps prunes the deps list after humans or generators have written them. They complement each other, but Gazelle in file mode already enforces a narrower deps surface for the languages it supports, so there is less for unused_deps to remove on Gazelle-managed packages.

At repo scale, trimming unused edges is not just a tidiness concern — large transitive closures are a measurable driver of rebuild volume and CI cost, and the graph analysis tooling in 5.3 Graph Analysis is the natural place to quantify the benefit once this workflow is routine.⁷