Why is a go test -race run so much slower and more memory-hungry than the same suite without it?

## Where the CPU goes In an ordinary build, reading a struct field is a load instruction. In a `-race` build the compiler emits a call into the race runtime before it, passing the address and the program counter. The runtime looks up the shadow state for that address, compares the accessing goroutine's current synchronisation state against what is recorded for previous accesses, and either updates the record or produces a report. That is orders of magnitude more work than the load itself, which is why the published guidance is a slowdown of roughly two to twenty times: code dominated by memory traffic in tight loops sits at the bad end, code dominated by syscalls, network waits or `time.Sleep` at the good end. This is also why the slowdown is uneven across a suite. A package of table-driven pure-function tests barely notices. A package whose tests hammer a shared map from many goroutines — exactly the code you most want instrumented — is where the multiple is largest. ## Where the memory goes The detector allocates shadow state alongside the application's memory to record, per location, which goroutines accessed it and with what ordering. The rule of thumb is five to ten times the memory of the uninstrumented run. Two things about that memory matter operationally: - It is *not* the Go heap. It is mapped and managed by the race runtime, so `GOGC` and `GOMEMLIMIT` do not shrink it. A job that OOMs under `-race` is not fixed by tuning the collector. - It scales with how much distinct memory the tests touch. A fixture that fills a map with a hundred thousand entries costs five to ten times more under instrumentation than it did before; shrinking the fixture to a thousand entries usually demonstrates the same race for a tenth of the footprint. The instrumented runtime also enforces a hard ceiling on the number of simultaneously live goroutines — a few thousand — and dies with a fatal message when a test exceeds it. Code that fans out tens of thousands of goroutines therefore has to be exercised at a smaller scale under the detector. ## Why the build is separate An instrumented package is a different artefact from the same package built normally, so it occupies its own entry in the build cache — the standard library included. The first `-race` invocation on a machine or container with a cold cache rebuilds essentially everything, which can dominate a short suite's wall clock. On CI this shows up as a job that is slow the first time and much faster afterwards, provided the build cache survives between runs. If your CI discards the cache each time, you pay that rebuild on every job, and caching `GOCACHE` between runs is often the single cheapest improvement available. The test cache is affected in the same way: an instrumented run and a plain run are different actions, so a cached plain result does not satisfy a `-race` invocation. ## The build tag and the cgo requirement Building with `-race` sets the `race` build tag. A file beginning with `//go:build race` compiles only in instrumented builds, and one with `//go:build !race` only in ordinary ones. That is occasionally useful for test helpers that should relax a timing assumption when everything is running an order of magnitude slower, or for a constant the package can consult to skip an assertion that only holds at full speed. On the supported platforms — 64-bit Linux, macOS and Windows among them — enabling the detector requires cgo. A build environment that pins `CGO_ENABLED=0`, which many container images do to get a static binary, makes the go command refuse the flag outright with a message telling you to enable cgo. This is a very common CI surprise: the same command works on a developer laptop and fails in the pipeline, and the fix is to set `CGO_ENABLED=1` for the race job (and to have a toolchain with a C compiler available) rather than to drop the flag. ## Budgeting for it When you plan a race job, do not reason from the plain suite's numbers. Measure the instrumented run once and take its duration and peak memory as the budget. Remember that `go test` builds and runs several package binaries concurrently — the `-p` flag, defaulting to `GOMAXPROCS` — so peak memory for the job is the per-binary cost multiplied by how many are in flight, not the cost of the largest one.