What does `go build -trimpath` strip from a Go binary, and why does a reproducible build need it?

## What ends up in a binary that you did not put there When the Go compiler compiles a file it records that file's name so that stack traces, `runtime.Caller`, and debugging information can point back at source. By default the recorded name is the **absolute path on the machine that did the build**. A panic on a developer laptop prints something like: ``` /Users/alice/work/app/handler.go:41 ``` and the same panic from the CI-built binary prints ``` /builds/runner-7/project/app/handler.go:41 ``` Those strings are real bytes inside the executable. Two builds of the same commit from two different directories therefore differ, even though nothing about the program differs. Absolute paths also leak information you may not want to publish: usernames, internal directory layouts, CI runner names. ## What -trimpath does `go build -trimpath` tells the toolchain to record trimmed names instead of absolute ones: - standard-library files are recorded under a `go`-rooted prefix rather than the path where the toolchain happens to be installed, - files from dependency modules are recorded as `module/[email protected]/file.go`, - files from the module being built are recorded under its plain import path. The result is a name that is stable across machines and still meaningful: `example.com/app/handler.go:41` tells you exactly as much as the absolute path did about *which* file, and nothing at all about *whose* machine. The same flag is available on `go test` and `go install`; whatever produces a compiled artefact you care about should carry it. ## Why reproducibility needs it, and why it is not sufficient A reproducible build is one where the same inputs give byte-identical output on any machine. The build directory is an input that nothing in your source controls, so it is the most common single reason two otherwise identical builds differ, and `-trimpath` is the fix. It is necessary but not sufficient. The other inputs still have to match: - the **toolchain version** — a different Go release compiles differently, and the version is recorded in the binary, - the **target settings** — `GOOS`, `GOARCH` and friends, - **`CGO_ENABLED`** and, if cgo is on, the C toolchain, which brings its own paths and its own nondeterminism, - the exact **dependency versions** resolved for the build, - any **build tags** and any flags that reach the compiler or linker, including whatever is sitting in `GOFLAGS`. Get all of those aligned and add `-trimpath`, and pure-Go builds of the same commit are byte-identical in practice. ## How to see whether a binary was trimmed The `go` command records the build settings that produced a binary, and `go version -m` prints them: ``` $ go version -m ./app ./app: go1.27.0 build -trimpath=true build CGO_ENABLED=0 ``` That is the fastest way to confirm that the artefact in front of you — the one CI published, not the one you just built — actually carried the flag. It is also the fastest way to spot that one of two differing binaries was built with it and the other was not. ## Interaction with the build cache Build flags are part of the key the build cache uses, so a trimmed build and an untrimmed build of the same package are different entries. Practical consequences: - if developers build plainly and CI builds with `-trimpath`, the two populate different halves of any shared cache, - turning `-trimpath` on for the first time looks like a cache-wide miss, because it is one; the next build is warm again, - setting it once in `GOFLAGS` for everyone keeps the whole team on one set of entries and stops the flag from being forgotten on some invocation. ## The cost The recorded paths no longer point at anything on disk, so a debugger or an editor jumping from a stack frame to a source line has to be told where the sources live rather than following the embedded path. For a production artefact that is the right trade; for a local iterative debug build there is no reason to pay it. That asymmetry — trimmed for anything you ship or hash, plain for local work — is the usual policy, and it is worth stating explicitly rather than leaving each engineer to guess.