Install the Go Toolchain and Configure PATH, GOROOT, and GOPATH on Linux, macOS, and Windows

Install Go from a tarball on Linux, a .pkg installer on macOS, or an MSI installer on Windows. Then run go version and confirm the selected executable with command -v go on Linux or macOS, or Get-Command go on Windows. Checking both matters: a valid Go installation can still lose to an older binary listed earlier in PATH.

Linux: replace the Go tree, then update PATH

Download the appropriate Linux archive and run the extraction command from the directory containing it. For the Go 1.23.0 AMD64 archive, use:

rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz

The removal is intentional. The official Go installation documentation warns against extracting a new archive into an existing /usr/local/go tree because doing so is known to produce broken installations. An archive installation replaces the distribution directory; it is not an in-place upgrade.

Next, add the toolchain's binary directory to PATH:

export PATH=$PATH:/usr/local/go/bin

For a per-user configuration, add that line to $HOME/.profile. It can instead go in /etc/profile for a system-wide configuration.

A profile edit might not take effect until your next login. To activate the per-user change immediately, run:

source $HOME/.profile

Alternatively, run the export command directly in the current shell. Verify both the toolchain and the executable selected by your shell:

go version
command -v go

The second command should point to the installation you intended to use, rather than an older copy elsewhere on the machine. Open a new terminal as a final persistence check and run go version again.

macOS: install the package and inspect PATH order

Run the macOS .pkg installer and follow its prompts. The package installs Go under /usr/local/go by default.

Add the binary directory to your shell startup file. For Bash, the documented example is:

echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bash_profile
source ~/.bash_profile

Then verify the installation:

go version
command -v go

The location check is particularly useful when a package-manager installation also exists. command -v go reveals which installation wins according to the current PATH order. If it reports a different Go executable than the package you just installed, correct the stale or competing path entry before debugging anything else.

Windows: run the MSI and refresh your terminal

Open the MSI installer and follow its prompts. Keep the default C:\Go installation path unless you have a reason to choose another location, and add the following directory to the system PATH variable:

C:\Go\bin

A Command Prompt opened before installation will not automatically receive the updated environment. Close and restart it before verifying Go. In PowerShell, run:

go version
Get-Command go

If Get-Command go points to an old location, remove that stale PATH entry or uninstall the older distribution. This is more reliable than assuming that the most recently installed copy is automatically selected.

A Windows setup may also define GOROOT as the installation directory:

GOROOT=C:\Go

GOROOT identifies the Go distribution directory; it is not the entry used to invoke the command from a terminal. C:\Go\bin still needs to be available through PATH.

Where GOPATH fits

The installation procedures above require the Go executable's directory to be reachable through PATH. For the project workflow in this guide, initialize a module rather than adding a manual GOPATH configuration step. The module path identifies the project's packages.

This keeps three concepts separate:

• PATH determines whether your shell can locate the go command.
• GOROOT, when explicitly configured in the Windows setup above, identifies the Go installation directory.
• The module path created with go mod init identifies packages in your project.

Check the installation with a first project

In a project directory that contains a Go program, initialize a module:

go mod init example.com/hello
go run .

The module path example.com/hello identifies the packages in the module. It does not have to resolve on the internet for local practice, although a module intended for publication should use a path you control.

After initialization, the project has its module metadata and go run . runs the program in the current directory. If go mod init works but a later command uses an unexpected toolchain, repeat the executable-location check rather than reinstalling immediately.

Troubleshooting multiple Go installations

Multiple Go versions can exist on one machine, but installing another copy does not guarantee that it becomes the active one. Diagnose selection directly:

# Linux or macOS
command -v go

# Windows PowerShell
Get-Command go

On Linux, keep the archive-installation model in mind: delete /usr/local/go before extracting the replacement archive. Do not layer a new archive over that directory, because obsolete files can remain and the resulting installation may be broken.

Package-manager installations are separate distributions and may use another location. On macOS, command -v go tells you whether /usr/local/go/bin/go or a package-manager binary currently wins. On Windows, Get-Command go provides the equivalent check; remove a stale PATH entry or uninstall the older distribution when it points somewhere unexpected.

The setup is complete when go version runs in a fresh terminal, the location command reports the intended executable, and your module can be initialized and run without exporting PATH again.