Installing Go from Source

Building Go from source means compiling the Go compiler and its entire toolchain directly from the source code instead of downloading a prebuilt binary distribution. This is not what most developers need—the official binary installers are faster and simpler—but there are specific cases where compiling from source is the right choice: you plan to contribute to the Go project itself, you need a custom build with local patches, you are bringing Go to a platform that has no official binary release, or you are a package maintainer producing distribution-specific packages.

The process hinges on one non‑obvious detail: the Go compiler is written in Go. To build a version of Go, you must already have a working Go installation. The existing Go toolchain that does the initial build is called the bootstrap toolchain. Understanding the bootstrap requirement and setting it up correctly is the part where most problems occur.

When Building from Source Makes Sense

You should consider a source build when you are:

• Contributing to Go itself. Fixing a compiler bug or working on a standard library improvement requires a development build from the master branch.
• Targeting an unsupported platform. If your operating system or CPU architecture combination is not on the official binary download list, a source build is the only way to get a working Go toolchain.
• Running Go inside a special environment. Minimal container images, embedded systems, or environments with unusual C libraries sometimes require building with specific flags or patches.
• Auditing or modifying the toolchain. Security researchers or infrastructure teams may need to compile from audited source with deterministic flags.

For all other development work, the precompiled binaries are recommended. They are tested, signed, and maintained by the Go team.

Prerequisites

Before you run the build, your system must have the following items ready. If any of them are missing, the build will fail with errors that often do not clearly explain what went wrong.

System Requirements

The Go compilers support a long list of operating systems and instruction sets. The exact combinations are documented in the Go Wiki. At minimum, you need a supported OS/arch pair, a few hundred megabytes of free disk space, and a reasonable amount of memory (any modern machine will suffice).

A Bootstrap Go Installation

Because the Go toolchain is written in Go, you need a working go command before you can build a new version from source. The minimum bootstrap version depends on the version you are trying to build:

• Go 1.22 and 1.23 require Go 1.20 or later as the bootstrap compiler.
• Go 1.24 and 1.25 require Go 1.22 or later.
• For earlier versions, the general rule is that Go 1.N requires Go 1.M, where M is N-2 rounded down to an even number.

There are four ways to obtain a bootstrap toolchain. The first two cover nearly every real‑world scenario.

1. Download a recent binary release – The easiest method. Go to go.dev/dl, download the archive for your platform, and extract it to a temporary location. Then point GOROOT_BOOTSTRAP to that directory.
2. Cross‑compile a bootstrap toolchain – If you are building on a platform for which no binary release exists, you can run the bootstrap.bash script on a different machine that already has Go installed. That script produces a self‑contained bootstrap tree you can transfer to the target machine.
3. Use gccgo – The GCC‑based Go frontend (gccgo 5 or later) can act as a bootstrap compiler. This is uncommon and mainly used by distribution maintainers.
4. Compile from Go 1.4 C sources – Go 1.4 was the last release whose compiler was written in C. You can build a Go 1.4 binary from its C source (provided you have a C compiler) and then use that binary as the bootstrap for newer versions. This method is almost never required today unless you are bootstrapping on a truly exotic architecture with no other options.

For the rest of this guide, we assume you are using a binary release as the bootstrap. If you already have a recent Go installed and on your PATH, that also works—make.bash will look for a go command in PATH first.

Git

Cloning the Go repository requires Git. Nearly every system already has it, but you can check with:

git version

If Git is missing, install it from your package manager or from git-scm.com. The Go build process does not use Git beyond the initial clone and checkout, so any reasonably recent version is fine.

A C Compiler (Optional)

Go can call C code through a mechanism called cgo. If you want the source‑built Go to support cgo, you must have a C compiler (typically gcc or clang) installed before running the build script. On Linux, install gcc with your package manager. On macOS, clang is included with Xcode Command Line Tools. On Windows, you will need a compiler like TDM‑GCC or MSYS2 MinGW.

If you do not need cgo—for example, you are building a pure Go development environment—you can tell the build to skip C support by setting the environment variable CGO_ENABLED=0 before running make.bash. The resulting Go toolchain will work perfectly for all pure Go programs but will not be able to compile packages that use import "C".

Step‑by‑Step Source Build

Each step depends on the previous one. Do not skip ahead, and verify that each step completes without errors before moving to the next.

# Download Go 1.22.5 for linux/amd64 (adjust URL for your OS/arch)
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
tar -C $HOME -xzf go1.22.5.linux-amd64.tar.gz
mv $HOME/go $HOME/go-bootstrap
export GOROOT_BOOTSTRAP=$HOME/go-bootstrap

sudo apt-get install git

export CGO_ENABLED=0

git clone https://go.googlesource.com/go $HOME/goroot
cd $HOME/goroot

git checkout go1.22.5

git checkout master

cd $HOME/goroot/src
./make.bash

---
Installed Go for linux/amd64 in /home/you/goroot
Installed commands in /home/you/goroot/bin
*** You need to add /home/you/goroot/bin to your PATH.

$HOME/goroot/bin/go run - <<EOF
package main
import "fmt"
func main() {
    fmt.Println("hello from source-built Go")
}
EOF

cd $HOME/goroot/src
./all.bash

export PATH=$HOME/goroot/bin:$PATH

Common Pitfalls with Source Builds

Even with the correct steps, a few issues tend to trip up newcomers. Being aware of them before you start will save time.

• Reusing the same directory for bootstrap and the main build. The bootstrap Go must stay at the version you downloaded. If you later git checkout a different tag in that directory, the bootstrap breaks. Always keep them in separate directories.
• Forgetting to set CGO_ENABLED=0 when no C compiler exists. This is the single most frequent build failure. The error messages mention missing headers or a broken toolchain, but the root cause is simply the absence of gcc. Set the variable and run make.bash again.
• Cloning into the default $HOME/go directory. Go uses $HOME/go as the default GOPATH. If you place the source tree there, the tools may pick up the wrong packages or configuration. Choose a different name, like goroot or go-src.
• Not adding the new bin directory to the PATH, then running an older go. After a successful build, if you type go version and still see the system Go, you are not using the source‑built binary. Check your PATH and which go.

Summary

Installing Go from source is a precise but not complex process once you understand the bootstrap requirement: you need an existing Go to build a new Go. The workflow is to obtain a bootstrap toolchain (usually a binary download), clone the source repository, run make.bash (or make.bat on Windows), and then add the resulting bin directory to your PATH.

The single most important insight to carry forward is the separation between the bootstrap toolchain and the target source tree—they must live in different directories, and you must not confuse them. The second is the role of CGO_ENABLED: unless you know you need C interop, building with CGO_ENABLED=0 removes the C compiler dependency and simplifies the build significantly.