Go Reference ยท The go Command and Tools
Go build flags and ldflags
Reference for Go build flags shared by go build, run, test and install: -ldflags -X -s -w, -gcflags, -race, -tags, -trimpath, -mod, -o, -v, -x and GOFLAGS.
Build flags are options understood by go build, go run, go install, go test, go vet and go list. They choose what is built (tags, race detector, mode), how the compiler and linker behave (-gcflags, -ldflags) and how much the go command tells you while it works (-v, -x).
The flags that matter most in daily work are -o (name the output), -race (find data races), -tags (select files, see Build constraints), -ldflags (control the linker, for example to stamp a version) and -trimpath (reproducible builds). You can set defaults for all of them in the GOFLAGS environment variable.
go build -o app -trimpath -ldflags="-s -w -X main.version=1.4.2" . go test -race -count=1 ./... go build -tags=integration,postgres ./cmd/server
Try it
Flags change the binary, and the binary can look at itself. These programs show the two ways your own code sees build flags.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
go build [-o output] [build flags] [packages]
| Flag | Description |
|---|---|
-o name |
Output file or directory. For go build with several packages, a directory. |
-v |
Print the names of packages as they are compiled. |
-x |
Print every command the go tool runs (compiler, linker, cgo). |
-n |
Print the commands but do not run them. |
-a |
Rebuild packages even if the cache says they are up to date. Rarely needed. |
-race |
Enable the data race detector. Needs cgo and a supported platform; binaries are several times slower and larger. |
-msan, -asan |
Memory and address sanitizers, which need cgo and a C toolchain with sanitizer support. |
-cover |
Build a binary that records coverage (GOCOVERDIR). Tests use this implicitly with go test -cover. |
-tags a,b |
Extra build tags, comma separated. |
-trimpath |
Remove file system paths from the binary, so builds from different folders match. |
-ldflags '...' |
Arguments for the linker, applied to the named packages (-ldflags='pkg=flags'; default: only the main packages). |
-gcflags '...' |
Arguments for the compiler, with the same pkg= syntax. |
-asmflags '...' |
Arguments for the assembler. |
-buildmode |
exe, pie, c-archive, c-shared, shared, plugin. |
-mod=mode |
readonly (default), vendor or mod. readonly refuses to change go.mod. |
-modfile file |
Use another go.mod, with its own go.sum beside it. |
-pgo file |
Use a CPU profile for profile-guided optimization (auto uses default.pgo in a main package). |
-buildvcs |
Embed version control data (auto, true, false). |
-C dir |
Change directory before doing anything. Must be the first flag (Go 1.20). |
-p n |
Number of builds run in parallel. |
-work |
Keep the temporary work directory and print its name. |
-json |
Machine-readable build output (Go 1.24). |
Common linker flags. -s omits the symbol table and -w omits DWARF debug data: together they shrink the binary but make debuggers and some profilers less useful. -X importpath.name=value sets a string variable. -extldflags passes arguments to an external C linker.
Common compiler flags. -gcflags=-m prints inlining and escape analysis decisions (-m -m is more verbose). -gcflags='all=-N -l' disables optimizations and inlining so a debugger can step through the code.
Errors and edge cases: a flag that needs a quoted value must be quoted for your shell, because the go tool splits the value itself. Without all=, -gcflags applies only to the packages named on the command line, not their dependencies.
Usage notes
GOFLAGSholds flags added to every command, such asGOFLAGS=-mod=vendor -trimpath. Flags from the command line are added after it and win. Show the current value withgo env GOFLAGS; change it persistently withgo env -w.- Stamp versions with
-X. It is the usual way to put a version or commit into a binary. The variable must be astringand must not be set by a function call. Since Go 1.18 you can also read VCS data fromdebug.ReadBuildInfo()without any flag. - The race detector only finds races that occur. Run tests with
-racein CI, with enough variety (parallel tests, realistic load) to exercise the code. - Cross-compilation uses environment variables, not flags:
GOOS=linux GOARCH=arm64 go build.CGO_ENABLED=0forces a pure Go build that does not depend on a C library. - Reproducible builds. Combine
-trimpath, a fixed Go toolchain, and-buildvcs=falseif you do not want commit data in the binary. - Test builds use the same flags (
go test -race -tags=integration -ldflags=...) plus test-specific ones such as-run,-countand-bench.