Which go command shows why a module you never required is in your build, and what does it print?

## Two graphs, and most confusion comes from mixing them Go maintains two distinct graphs, and "why is this dependency here?" has a different answer in each. The **module requirement graph** is the one written down in `go.mod` files. Your `go.mod` has `require` lines; each required module has its own `go.mod` with its own `require` lines; the union of all those edges is the requirement graph. Version selection walks that graph to produce the *build list* — one chosen version per module path. The **package import graph** is what the compiler actually follows. It starts at the packages you build and follows `import` statements, package by package, until it closes. Only packages in this graph get compiled and linked into your binary. These graphs are not the same size. A module can be required — because some dependency's `go.mod` mentions it — while not a single one of its packages is imported by anything you build. That module appears in `go mod graph` output and contributes nothing to your program. ## What `go mod why` does `go mod why` takes package paths. With `-m`, it takes module paths instead and reports, for each one, the shortest path in the package import graph from a package in the main module to *some* package in that module: ``` $ go mod why -m golang.org/x/text # golang.org/x/text example.com/service/internal/report golang.org/x/text/language ``` Read it top-down: `internal/report` (yours) imports `golang.org/x/text/language`, which lives in the `golang.org/x/text` module. One hop, and now you know exactly which of your files to look at. When nothing imports it: ``` $ go mod why -m golang.org/x/text # golang.org/x/text (main module does not need module golang.org/x/text) ``` That is not an error and the exit status stays zero. It means the module is in the requirement graph — probably because some other dependency declares it — but no package of it is compiled into your build. `go mod why -m all` runs the same report over every module in the build list, which is the fastest way to see the whole provenance picture at once. The `-vendor` flag makes it ignore tests of dependencies, matching what a vendored build would need. ## Why this is the first thing to run when reviewing a new import A pull request that adds one line — `import "example.com/lib"` — routinely adds several `require` lines to `go.mod`. The reviewer's question is not "are these lines legitimate" but "which of them are now *code in the binary*, and which are just graph bookkeeping". `go mod why -m` separates those two populations in seconds, and it names the file in your own repository that is responsible, so the conversation on the PR is about a concrete import site rather than about a diff in `go.mod`. The package-level counterpart is `go list -deps ./...`, which enumerates every package the build compiles, standard library included. Between the two you can say precisely what a change added: `go mod why` gives provenance per module, `go list -deps` gives the inventory per package. ## What `go mod graph` is for instead ``` $ go mod graph example.com/service golang.org/x/[email protected] example.com/service example.com/[email protected] example.com/[email protected] golang.org/x/[email protected] ``` Each line is one requirement edge: the module on the left declares a requirement on the module on the right. The main module appears with no version. This is the right tool when you want to know *who declared* a requirement, especially when two dependencies declare different versions of the same module. It is the wrong tool for "is this code in my binary", because a requirement edge is not an import. ## Common mistakes - Reading the `require` block as an inventory of shipped code. It is a set of version constraints, not an import list. - Assuming `go mod graph` output is an import chain. It is requirement edges, and it usually contains modules that contribute nothing to the build. - Forgetting that test files count. A module can be needed only by the tests of a package you import; `go mod why` will show that path, and `-vendor` excludes tests of dependencies if that is the view you want.