Go Environment Setup on macOS

First PublishedJun 17, 2026ByAtif Alam

This page walks through setting up Go on macOS: check or install the toolchain, fix PATH, bootstrap ~/go, install CLI tools with go install, and verify with a minimal module. For a first CLI after setup, see Go for small ops tools.

Check What You Already Have

1
go version
2
which go

If both work, note the version and skip to GOROOT, GOPATH, and modules unless you need a newer release.

Expected output looks like go version go1.22.x darwin/arm64 on Apple Silicon or darwin/amd64 on Intel Macs.

If go is not found, install using one of the options below — pick one path and stick with it.

Avoid mixing Homebrew and the official .pkg installer. Two installs produce confusing which go output and duplicate PATH entries.

Install Go

Recommended — Homebrew

Same pattern as other macOS guides in this library:

1
brew install go
2
go version

On Apple Silicon, Homebrew usually puts go on PATH via /opt/homebrew/bin. You typically do not need to add /usr/local/go/bin when you use Homebrew only.

Upgrade later with:

1
brew upgrade go

Alternative — Official `.pkg` installer

Download the macOS package from go.dev/dl and run it. This installs Go under /usr/local/go.

Verify:

1
go version

If go is not found, add the official binary directory to ~/.zshrc:

1
export PATH=$PATH:/usr/local/go/bin
2
source ~/.zshrc

Multiple Go versions — optional

Most developers need one Go release. When you need more:

Approach	When it fits
Official installs from go.dev/dl	Pin a specific version per machine; simple and reliable
Homebrew versioned formulae	Team already uses Homebrew for everything
asdf with the Go plugin	Same “one tool, many runtimes” idea as pyenv for Python
gvm	Legacy option; can be fragile on newer macOS — use only if your team already standardizes on it

Example gvm flow (optional):

1
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
2
gvm install go1.22.0
3
gvm use go1.22.0 --default

Replace go1.22.0 with a current version from go.dev/dl.

GOROOT, GOPATH, and modules

Go uses a few directory concepts:

GOROOT — where the Go toolchain itself is installed (Homebrew or /usr/local/go).
GOPATH — your Go workspace; default ~/go. Holds go install binaries (~/go/bin) and the module download cache (~/go/pkg/mod).
Modules — modern projects use go.mod in any folder. You do not need to put source code under $GOPATH/src.

1
go env GOROOT
2
go env GOPATH
3
go env GOMODCACHE
4
go env

Installed CLI tools from go install land in $GOPATH/bin (usually ~/go/bin).

The ~/go directory does not exist on a fresh install. That is normal — Go creates it when you first go install a tool or run go mod init in a project.

Bootstrap `~/go` with `goimports`

Install a standard tool that formats imports and bootstraps your workspace:

1
go install golang.org/x/tools/cmd/goimports@latest

This will:

Create ~/go/ and ~/go/bin/ if they are missing
Install the goimports binary under ~/go/bin

Verify the binary exists (full path works even before the next step):

1
ls ~/go/bin
2
# Expected: goimports

go install does not require $GOPATH/bin on PATH, but which goimports only succeeds after you add that directory to PATH below.

Add Go Tools to Your PATH

Add these lines to ~/.zshrc so installed tools are callable from anywhere:

1
export GOPATH=$HOME/go
2
export PATH=$PATH:$GOPATH/bin

If you used the official .pkg installer, also ensure the Go toolchain is on PATH:

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

If you used Homebrew only, the GOPATH and $GOPATH/bin lines above are usually enough — skip /usr/local/go/bin unless which go points there.

Apply changes:

1
source ~/.zshrc
2
which goimports

Example `~/.zshrc` blocks

Homebrew install:

1
# Go setup (Homebrew)
2
export GOPATH=$HOME/go
3
export PATH=$PATH:$GOPATH/bin

Official .pkg install:

1
# Go setup (official installer)
2
export GOPATH=$HOME/go
3
export PATH=$PATH:/usr/local/go/bin
4
export PATH=$PATH:$GOPATH/bin

Verify With a Tiny Module

Confirm the toolchain end-to-end:

1
mkdir -p ~/hello-go && cd ~/hello-go
2
go mod init example.com/hello

Create main.go:

1
package main
2

3
import "fmt"
4

5
func main() {
6
  fmt.Println("Hello, Go!")
7
}

Run it:

1
go run .

Expected: Hello, Go!

For a slightly larger CLI with flags, continue to Go for small ops tools. Cloning private modules may require OpenSSH client keys and GOPRIVATE — see that ops page for a one-line sketch.

Quick Reference

Task	Command
Check Go version	`go version`
Find GOROOT / GOPATH	`go env GOROOT` / `go env GOPATH`
See all Go env vars	`go env`
Install a Go tool	`go install <package>@latest`
Upgrade (Homebrew)	`brew upgrade go`
Reload shell config	`source ~/.zshrc`

Key Takeaways

Run go version and which go before installing — avoid duplicate toolchains.
Homebrew vs official .pkg need different PATH lines; do not blindly copy both.
GOPATH (~/go) holds go install tools and the module cache; projects live anywhere with go mod init.
Bootstrap with go install …/goimports@latest, then put $GOPATH/bin on PATH.
Verify with a tiny module and go run . before moving on to CLIs or services.

Go overview — this section’s landing page
Go for small ops tools — flags, modules, cross-compile
Go chi service layout — production HTTP service structure
OpenSSH client keys — clone private Go modules over SSH
Python project environment setup — parallel macOS setup flow for Python