Getting started

This page covers building Go from source in this repository. If you only want to use Go, install a binary release from https://go.dev/dl/. The instructions below are for contributors and distribution maintainers who modify or rebuild the toolchain.

Prerequisites

The Go toolchain is self-hosted, so building it requires a working Go compiler:

• A bootstrap Go toolchain. The default expected location is $HOME/sdk/go1.24.6, $HOME/go1.24.6, or $HOME/go1.4, in that order. Set GOROOT_BOOTSTRAP to override.
• A Unix-like shell (bash, zsh, etc.) on Linux, macOS, BSD, etc. On Windows use make.bat instead. On Plan 9 use make.rc.
• A C compiler (gcc or clang) for cgo and the runtime's C bits. Optional if CGO_ENABLED=0.
• Git, since the build embeds a version stamp from the working tree.

The minimum bootstrap version is hard-coded at the top of src/make.bash:

bootgo=1.24.6

This bootgo version is bumped roughly once a year following Go's bootstrap policy (a release plus four prior versions).

Build the toolchain

Run from src/:

./make.bash       # Linux/macOS/BSD
./make.bat        # Windows
./make.rc         # Plan 9

The script does the following (see src/make.bash for the full detail):

1. Locates $GOROOT_BOOTSTRAP/bin/go.
2. Builds cmd/dist using the bootstrap toolchain.
3. Hands off to ./cmd/dist/dist bootstrap, which:
   • Builds the new compile, link, asm, and supporting tools.
   • Rebuilds the toolchain with itself (one or two passes for stability).
   • Builds the standard library and remaining commands.
4. Installs everything into $GOROOT/bin and $GOROOT/pkg.

After a successful build:

$ ../bin/go version
go version devel go1.27-... linux/amd64

Run the full test suite

./all.bash        # Linux/macOS/BSD: build + run all tests
./all.bat         # Windows
./all.rc          # Plan 9

all.bash calls make.bash then run.bash. run.bash invokes cmd/dist test, which runs:

• go test std cmd — every standard library and command package's tests.
• The test/ directory's compiler/runtime regression tests via cmd/internal/testdir.
• API compatibility checks (cmd/api).
• Various race-mode and short-mode subsets.

A full all.bash takes minutes to over an hour depending on the host.

Faster development loops

For day-to-day work, you usually do not need a full bootstrap:

# After the first ./make.bash, your $PATH should include $GOROOT/bin.
# Then to rebuild a single tool with the freshly built toolchain:

go install cmd/compile        # rebuild the compiler
go install cmd/link           # rebuild the linker
go install cmd/go             # rebuild the go command

# Run a single package's tests using the freshly built toolchain:
go test ./...
go test -short -run TestFoo ./fmt

For quicker iteration on the compiler, cmd/compile/README.md recommends toolstash:

go install golang.org/x/tools/cmd/toolstash@latest
toolstash save                                  # save current good toolchain
# ... edit cmd/compile sources ...
toolstash restore && go install cmd/compile     # rebuild with known-good toolchain
go test cmd/compile/...

Environment knobs

The most useful environment variables when building or working on Go (from src/make.bash and src/cmd/dist):

Variable	Purpose
GOROOT_BOOTSTRAP	Path to a Go ≥ 1.24.6 toolchain used to build this one
GOOS, GOARCH	Target OS and architecture
GOHOSTOS, GOHOSTARCH	Host OS/arch (only set when cross-compiling)
CGO_ENABLED	0 to skip C bridging entirely; 1 to enable
GO_GCFLAGS, GO_LDFLAGS	Extra flags for compile and link invocations
CC, CC_FOR_TARGET, CXX_FOR_TARGET	C/C++ compilers used for cgo and runtime support
GOEXPERIMENT	Enable experimental features (e.g., genericmethods); see src/internal/goexperiment/
GOFLAGS	Default flags applied to go invocations

Where things land

After make.bash, the layout under $GOROOT is:

• bin/ — go, gofmt, cgo, compile, link, ... user-facing binaries.
• pkg/tool/<host>/ — internal toolchain binaries (compile, link, asm, vet, etc.).
• pkg/<host>/ — compiled standard library archives (when not using the build cache).
• src/ — sources you just built from.

Common problems

• "GOROOT_BOOTSTRAP must not be set to $GOROOT" — clear or relocate the variable; bootstrap and target trees must be different directories.
• "Cannot find $GOROOT_BOOTSTRAP/bin/go" — install a Go ≥ 1.24.6 release at the expected path or set GOROOT_BOOTSTRAP.
• "linked object header mismatch" — your build cache contains objects from a different toolchain. toolstash restore && go install cmd/... (or go clean -cache) usually fixes it.
• gold 2.20 detected — the build refuses to run because that linker version produces broken binaries. Switch to a newer binutils or lld.

Where to read next

• Architecture — high-level diagram of how the pieces fit together.
• How to contribute → development workflow — Gerrit, CL workflow, code review.
• How to contribute → testing — what go test, cmd/dist test, and test/ do.
• Components → Go command — what happens inside go build, go test, etc.