Download and Install

Purpose and Scope

This page orients a new Go user from download choice to a working local toolchain. The Go repository itself is not the download service, but its top-level README points readers to the official binary release page and to source-build instructions when a prebuilt archive is unavailable. In practice, installation means placing a Go distribution on the machine, making the go command reachable from the shell, and verifying that the installed command reports a version. The same installed tree also contains lower-level tools used behind the scenes by builds, tests, cgo, profiling, and assembly workflows.

Sources: README.md

The fastest path for most users is the official binary distribution. The public install guide instructs Linux users to remove any previous /usr/local/go tree, extract the downloaded archive into /usr/local, add /usr/local/go/bin to PATH, and run go version. macOS and Windows use installer packages that place the Go distribution in the standard location and update the user environment. The repository README supports that workflow by directing binary-release users to https://go.dev/dl/ and then to https://go.dev/doc/install for operating-system-specific steps.

Sources: README.md

Source installation is the fallback for platforms where no binary distribution exists, or for contributors and port maintainers who need to build the toolchain themselves. The README describes this as a separate path from binary installation and points to https://go.dev/doc/install/source. That distinction matters: a binary archive is an already-built Go distribution, while source installation starts from a checkout and produces the distribution locally. New users should prefer the binary path unless they are intentionally working on a platform port, debugging the toolchain, or contributing to the Go project.

Sources: README.md

Relevant Source Files

• README.md - Defines the repository as the Go programming language source tree, identifies the canonical Git repository and GitHub mirror, links to official binary downloads, and points to source installation instructions.
• misc/go_android_exec/main.go - Shows a platform execution wrapper used by the Go tool when running binaries on Android devices via adb, illustrating that installed and source-built trees may include platform-specific support programs.
• src/cmd/addr2line/main.go - Implements go tool addr2line, a bundled diagnostic helper used by pprof to translate program counters to function and file-line information.
• src/cmd/asm/main.go - Implements the Go assembler entry point, including architecture selection, flag parsing, object-file writing, and integration with build configuration.
• src/cmd/cgo/main.go - Implements cgo processing for packages that import C, including collection of Go files, C references, compiler options, and generated output metadata.
• src/cmd/compile/internal/gc/main.go - Implements the compiler main pipeline that parses flags, initializes architecture state, type-checks Go packages, compiles functions, and writes compiled package data.

Installation Workflow

For a binary install, treat the downloaded archive or installer as the whole Go distribution. Do not merge a new archive into an existing Go tree; the official guidance is to remove the previous tree first, then extract or install the new one. This prevents stale tools or libraries from remaining on disk and being accidentally selected by the build. After the distribution is installed, the only shell configuration required for normal use is that the distribution’s bin directory is on PATH, so that invoking go finds the newly installed command.

rm -rf /usr/local/go
tar -C /usr/local -xzf go1.14.3.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
go version

On macOS and Windows, the same conceptual steps are usually performed by a package installer: place the Go distribution in the standard location, update the command search path, and then open a new terminal if needed. Verification is intentionally simple. Run go version from a fresh command prompt and confirm that it prints the installed version. If the shell cannot find go, the install may still be correct, but the user environment is not yet pointing to the distribution’s bin directory.

Once installation is verified, the next practical distinction is between go run, go build, and go install. The getting-started tutorial uses go run as a shortcut while editing, because it compiles and runs without leaving a reusable executable in the project directory. The compile-and-install tutorial then introduces go build for producing a local executable and go install for compiling and installing a command into the Go install directory. That path is what lets users run their own command without typing its filesystem location.

go build
./hello
go install

What the Distribution Contains

The installed Go distribution is more than one executable. The top-level go command coordinates package loading, builds, tests, module operations, and subtool execution, while lower-level commands under src/cmd implement pieces of the toolchain. The supplied source evidence shows representative command entry points that become relevant after installation: the compiler, assembler, cgo processor, addr2line helper, and an Android execution wrapper. Readers do not normally invoke all of these directly, but their presence explains why a Go distribution has a structured tool tree rather than a single standalone binary.

Sources: src/cmd/compile/internal/gc/main.go, src/cmd/asm/main.go, src/cmd/cgo/main.go, src/cmd/addr2line/main.go, misc/go_android_exec/main.go

The compiler entry point in src/cmd/compile/internal/gc/main.go describes the core build responsibility: parse command-line flags and source files, type-check the package, compile functions to machine code, and write compiled package data. The assembler entry point in src/cmd/asm/main.go chooses an architecture from the build configuration, parses assembly input, and writes object files. Together, these files ground an important installation expectation: after go version works, go build can drive a complete compile pipeline for ordinary Go source and for packages that include Go assembly.

Sources: src/cmd/compile/internal/gc/main.go, src/cmd/asm/main.go

Some installed tools support optional or specialized workflows. src/cmd/cgo/main.go processes files that import C, records C references and compiler or linker options, and produces generated Go and C-facing metadata. src/cmd/addr2line/main.go is a minimal go tool addr2line implementation used by pprof to map addresses back to function names and source locations. misc/go_android_exec/main.go shows how Go’s test execution can be adapted for Android by copying needed state to a device and running binaries through adb. These tools demonstrate that installation enables an ecosystem of commands, not only compilation of basic programs.

Sources: src/cmd/cgo/main.go, src/cmd/addr2line/main.go, misc/go_android_exec/main.go

Binary Versus Source Installation

Choose the binary distribution when your operating system and architecture are listed on the official downloads page. It is the supported on-ramp for learning Go, using modules, compiling applications, and following tutorials. A binary install gives you a consistent, versioned toolchain without requiring a bootstrap compiler or local build of the repository. This is also the best choice when you are diagnosing application code rather than changing the compiler, standard library, or runtime.

Sources: README.md

Choose source installation when the README’s condition applies: no binary distribution is available for your operating-system and architecture combination. It is also the natural choice for contributors who need to modify files in this repository and then rebuild the toolchain. Source installation requires following the source-specific instructions rather than simply copying files into a Go installation directory. Keeping these paths separate avoids a common failure mode: mixing generated toolchain artifacts from one version with source files or binaries from another version.

Sources: README.md

Post-Install Checks and Next Steps

After installing, run go version first, then create or open a small module and confirm that go run, go build, and optionally go install behave as expected. For a new command, the tutorial flow is to build in the package directory, run the produced executable directly, then install it to the Go command install path so it can be executed by name. If that final command is not found, the install directory for user-built binaries may need to be added to the shell path separately from the Go distribution’s own bin directory.

The next page for a brand-new user is Getting Started, because it begins with the installed command and moves into module initialization, a first source file, running code, and calling external module code. If you are preparing to develop Go itself, read the source-installation and contribution material before changing the repository. If you are installing only to use Go for applications, continue with modules, testing, and build/install workflows rather than the internal command sources described here.