Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go build command

Reference for go build: output names, packages vs binaries, cross-compiling with GOOS and GOARCH, build tags, ldflags, -trimpath and reproducible builds.

go build compiles the packages you name, together with their dependencies. For a main package it writes an executable, named after the directory (or after the module path's last element) and placed in the current directory. For any other package it compiles and discards the result, which makes it a quick way to check that code builds.

Go builds are fast and self-contained: the output is usually a single static binary that you can copy to a server. Cross-compiling needs nothing but two environment variables.

Terminal
go build                     # build the package in the current directory
go build -o bin/app ./cmd/app
go build ./...               # compile everything, write nothing
GOOS=linux GOARCH=arm64 go build -o app-linux-arm64 .

Try it

The site compiles these programs with go build semantics, so they show what the build records in a binary and how build constraints decide which files take part.

Go What a build records inside the binary

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 Build constraints decide which files are compiled

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 file Output file name. If it names an existing directory, the binary goes inside it. With several packages, -o must be a directory.
-v Print the names of packages as they are compiled.
-x Print every command the tool runs (compiler, linker). -n prints them without running.
-race Build with the race detector (needs cgo on most platforms).
-tags a,b Extra build tags, matched against //go:build lines.
-ldflags '...' Flags for the linker. Common: -s -w (strip symbol table and DWARF, smaller binary) and -X pkg.name=value (set a string variable).
-gcflags '...' Flags for the compiler, for example -gcflags=-m to print inlining and escape analysis decisions.
-trimpath Remove local file system paths from the binary, which helps reproducible builds and avoids leaking directory names.
-buildvcs=false Do not stamp version control information (stamping is automatic when building inside a repository).
-pgo=file Use a CPU profile for profile-guided optimization (-pgo=auto uses default.pgo in the main package).
-cover Build a binary instrumented for coverage.
-buildmode=... Output kind: exe (default), pie, c-shared, plugin and others.
-a, -work, -p n Rebuild everything, keep the work directory, set parallelism.

Environment variables that matter: GOOS, GOARCH, CGO_ENABLED, GOFLAGS, GOAMD64, GOARM. The go env output is described in go env.

Errors: compile errors list file:line:col: message and the build exits nonzero. At most ten errors are shown per package unless you pass -gcflags=-e.

Usage notes

  • Cross-compiling. Set GOOS and GOARCH (linux/amd64, linux/arm64, darwin/arm64, windows/amd64, js/wasm...). go tool dist list prints every supported pair. Pure Go code builds anywhere; code that needs cgo needs a C cross toolchain, so most people also set CGO_ENABLED=0 for static binaries.
  • Static binaries. With CGO_ENABLED=0, the net and user packages use pure Go implementations, so the result runs even in an empty container image.
  • Version stamping. Since Go 1.18 the binary records the module version, VCS revision and dirty flag, readable with debug.ReadBuildInfo() or go version -m binary. Use -ldflags -X when you want your own string.
  • Smaller binaries. -ldflags="-s -w" makes the file noticeably smaller. Debuggers lose symbol and line information, but Go panics still print readable traces because the runtime keeps its own tables.
  • Reproducible builds. Use the same Go version, the same inputs, -trimpath and -buildvcs=false or a fixed VCS state, and the output is byte-for-byte identical.
  • Build cache. Results are cached in go env GOCACHE. go clean -cache empties it. You rarely need -a.
  • go build on a library writes nothing. It is a type check plus compile. go vet goes further; see go vet.
  • File name suffixes act as constraints too: x_linux.go, x_windows_amd64.go and x_test.go are filtered by name before any //go:build line is read.
  • Multiple main packages. go build ./... builds them all but writes no files; build each command with its own -o.