Configuration

Configuration in this repository takes three forms:

1. Build-time environment variables read by make.bash and cmd/dist.
2. Tool-time environment variables read by go, compile, link, etc.
3. Runtime environment variables read by the embedded runtime in every Go binary (GODEBUG, GOMAXPROCS, GOGC, GOMEMLIMIT, etc.).

This page collects the most important ones in each category. The canonical list is go help environment plus doc/godebug.md.

Build-time (consumed by make.bash / cmd/dist)

Variable	Effect
GOROOT_BOOTSTRAP	Path to a working Go ≥ 1.24.6 used to build this one
GOROOT_FINAL	Where the toolchain expects to be installed (legacy; -trimpath is preferred)
GOOS, GOARCH	Target OS/arch for the built toolchain
GOHOSTOS, GOHOSTARCH	Host OS/arch (only set when cross-compiling)
GO_GCFLAGS	Extra flags to compile for every package built
GO_LDFLAGS	Extra flags to link for every binary built
CGO_ENABLED	0 to disable cgo; 1 to enable
CC, CC_FOR_TARGET, CC_FOR_<os>_<arch>	C compilers for cgo
CXX_FOR_TARGET, CXX_FOR_<os>_<arch>	C++ compilers
FC	Fortran compiler
PKG_CONFIG	pkg-config binary used for #cgo pkg-config:
GOEXPERIMENT	Comma-separated experiment list to enable in the build (e.g., genericmethods)
GOBUILDTIMELOGFILE	If set, log timing data from make.bash

Reference: top of src/make.bash.

go command environment

These can be set in shell, written to ~/.config/go/env via go env -w, or seeded by $GOROOT/go.env. Hierarchy: env > user file > go.env.

Variable	Effect
GOROOT	Go installation root
GOPATH	Workspace + module cache root (default ~/go)
GOBIN	Where go install puts binaries (default $GOPATH/bin)
GOMODCACHE	Module download cache (default $GOPATH/pkg/mod)
GOCACHE	Build cache root (default ~/.cache/go-build)
GOFLAGS	Default flags applied to every go invocation
GOPROXY	Module proxy URL list (default https://proxy.golang.org,direct)
GOSUMDB	Checksum DB host (default sum.golang.org)
GOPRIVATE / GONOPROXY / GONOSUMCHECK	Patterns for private repos
GOAUTH	Authentication for module fetches
GOTOOLCHAIN	auto, local, path, or a specific version
GO111MODULE	on, off, auto (modules vs. GOPATH mode)
GOWORK	Workspace file location (default go.work upward)
GOFIPS140	FIPS-140 mode toggle
GOTELEMETRY	on, off, local
GOTELEMETRYDIR	Where to write local telemetry counters
GOEXPERIMENT	Compile-time experiment list (must match toolchain build)
GOAMD64, GOARM, GOMIPS, GOPPC64, GORISCV64	Microarch level for the target

Run go env for the current values; go help environment for the canonical descriptions.

Compiler / linker flags via -gcflags and -ldflags

go build -gcflags='all=-N -l'        # disable optimization + inlining (debugger-friendly)
go build -gcflags=-m=2               # log inlining + escape analysis
go build -ldflags='-s -w'            # strip symbol table + DWARF
go build -ldflags='-X path.Var=value' # set a string variable at link time
go build -trimpath                   # strip absolute paths

go tool compile -d help and go tool compile -d ssa/help list the full sets of debug knobs (-d).

Runtime: GODEBUG

GODEBUG controls the embedded runtime's verbose-logging and behavior-toggling knobs. Set as a comma-separated key=value list. Documented in doc/godebug.md.

Selected keys:

Key	Effect
gctrace=1	One line per GC cycle on stderr
gccheckmark=1	Re-mark stop-the-world to verify mark phase
gcpacertrace=1	Pacer decisions per cycle
gcstoptheworld=1/2	Convert concurrent GC into STW (debugging only)
allocfreetrace=1	Trace every allocation/free (very verbose)
schedtrace=N	Scheduler stats every N ms
scheddetail=1	Verbose scheduler dumps
cpu.<feature>=on/off	Toggle CPU features at startup
asyncpreemptoff=1	Disable async preemption
cgocheck=0..2	Cheap (default), expensive checks for cgo pointer rules
efence=1	Don't reuse memory after free (helps catch use-after-free)
madvdontneed=1	Use MADV_DONTNEED instead of MADV_FREE on Linux
inittrace=1	Print init function durations
panicnil=1	Restore old panic(nil) behavior
tlsdebug=1	Print TLS handshake details
tracebackancestors=N	Show parent goroutine stacks in tracebacks

Many GODEBUG settings are tied to a specific Go language version: setting go 1.20 in go.mod selects pre-1.21 default behavior for the loopvar knob, etc. The mechanism lives in src/internal/godebug/ and src/internal/godebugs/.

Runtime: other env vars

Variable	Effect
GOMAXPROCS	Max simultaneous OS threads running Go code (default = NumCPU)
GOGC	GC trigger ratio (default 100 = trigger at 2× live heap); off disables
GOMEMLIMIT	Soft memory cap honored by the GC
GOTRACEBACK	Verbosity of crash traceback (none, single, all, system, crash, wer)
GORACE	Race detector flags
GODEBUG	(above)
GOMAXPROCS	Set runtime parallelism

Build constraints

In .go files, //go:build expr constraints are evaluated using GOOS, GOARCH, build tags, and Go version:

//go:build linux && (amd64 || arm64) && !cgo
//go:build go1.21

In .s files, the older // +build form is also recognized.

File-name suffixes (_linux.go, _amd64.go, _test.go) are implicit constraints.

Where to read next

• How to contribute → debugging — using GODEBUG and friends to investigate.
• Components → Runtime — what runs behind these knobs.
• doc/godebug.md — the canonical, complete GODEBUG reference.