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.
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.
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 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
GOOSandGOARCH(linux/amd64,linux/arm64,darwin/arm64,windows/amd64,js/wasm...).go tool dist listprints every supported pair. Pure Go code builds anywhere; code that needs cgo needs a C cross toolchain, so most people also setCGO_ENABLED=0for 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()orgo version -m binary. Use-ldflags -Xwhen 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,
-trimpathand-buildvcs=falseor a fixed VCS state, and the output is byte-for-byte identical. - Build cache. Results are cached in
go env GOCACHE.go clean -cacheempties it. You rarely need-a. go buildon a library writes nothing. It is a type check plus compile.go vetgoes further; see go vet.- File name suffixes act as constraints too:
x_linux.go,x_windows_amd64.goandx_test.goare filtered by name before any//go:buildline is read. - Multiple
mainpackages.go build ./...builds them all but writes no files; build each command with its own-o.