Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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.

Go A variable the linker can overwrite

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.

Go Reading the build settings of a running program

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

Terminal
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

  • GOFLAGS holds flags added to every command, such as GOFLAGS=-mod=vendor -trimpath. Flags from the command line are added after it and win. Show the current value with go env GOFLAGS; change it persistently with go env -w.
  • Stamp versions with -X. It is the usual way to put a version or commit into a binary. The variable must be a string and must not be set by a function call. Since Go 1.18 you can also read VCS data from debug.ReadBuildInfo() without any flag.
  • The race detector only finds races that occur. Run tests with -race in 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=0 forces a pure Go build that does not depend on a C library.
  • Reproducible builds. Combine -trimpath, a fixed Go toolchain, and -buildvcs=false if 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, -count and -bench.