Where do you put a Go PGO profile so that `go build` uses it without extra flags?

## What PGO is in Go Profile-guided optimization (PGO) means feeding a recording of how the program actually behaved back into the compiler, so the compiler optimises the code paths that really run hot rather than guessing from the source alone. Go shipped PGO as a preview in Go 1.20 and made it generally available in Go 1.21. The input is not a special format: it is a normal **pprof CPU profile**, the same protocol-buffer file `runtime/pprof` and the `net/http/pprof` handlers produce, and the same thing `go tool pprof` reads. That matters, because it means the profile can come from a real production instance under real traffic rather than from a synthetic benchmark rig. ## Where the file goes The go command looks for a file literally named `default.pgo` in the **directory of the main package being built**. For a repository laid out as: ``` cmd/api/main.go cmd/api/handlers.go cmd/api/default.pgo ``` `go build ./cmd/api` picks up `cmd/api/default.pgo` automatically. If you build several binaries out of one module, each `main` package directory needs its own profile — there is no module-wide profile, and a `default.pgo` dropped into a library package is simply ignored. ## The -pgo flag `-pgo` is a build flag shared by `go build`, `go install`, `go run` and `go test`, and it takes three shapes: - `-pgo=auto` — the default since Go 1.21: use `default.pgo` from the main package directory if it exists, otherwise build normally. - `-pgo=off` — build with no profile at all, even if `default.pgo` is sitting there. This is how you produce the baseline half of an A/B comparison. - `-pgo=/path/to/some.pprof` — use an explicit profile file. Useful in CI when the profile is fetched from an artifact store instead of committed. Because `auto` is the default, checking the file in is the entire opt-in. Nobody has to remember a flag, which is exactly the point: a developer who clones the repo and runs `go build` gets the same optimisation the release build gets. ## Getting a representative profile The profile should describe the workload you care about. For an HTTP API serving product traffic — a handler that reads an id out of the request path and queries the database — a profile captured from one instance during ordinary daytime traffic is far more useful than one captured from a load test that hammers a single endpoint, because PGO will optimise for whatever the samples say is hot. If you have several instances or several traffic shapes, you can merge profiles before committing them; `go tool pprof` will merge inputs and write a combined proto profile: ``` go tool pprof -proto a.pprof b.pprof c.pprof > cmd/api/default.pgo ``` Merging is usually the right move: an unmerged profile from a single instance can encode that instance's quirks (a stuck client, a cold cache) as the program's hot path. ## What PGO does not require and does not do It does not require a separate instrumented build — Go's sampling profiler runs in a normal binary at low overhead, which is why capturing from production is practical. It does not change program semantics; a PGO build and a non-PGO build of the same source behave identically, they just have different machine code. And it is not a correctness gate: a profile that no longer matches the code is not an error, just a less useful hint (the compiler will simply find fewer matches). The main cost to be aware of is build time and cacheability. The profile influences code generation across the whole build, dependencies included, so introducing or changing `default.pgo` invalidates cached package builds and forces recompilation. That is a build-pipeline consideration rather than a reason to avoid PGO, but it is the reason teams notice the first PGO-enabled CI run taking longer than usual.