Install Go on macOS

Before You Start

• Applies to: Go 1.21+ (examples verified with Go 1.22) · Prerequisites: Get Started · Read time: about 7 min

This guide will help you install Go language on macOS system.

Download Go

First, download the Go installation package suitable for your macOS system from the official website.

Choose the corresponding version based on your system architecture:

• darwin-amd64 - Intel Mac (x86-64 architecture)
• darwin-arm64 - Apple Silicon Mac (ARM64 architecture)

Installation Methods

Method 1: Using Installer Package (Recommended)

This is the simplest installation method, suitable for most users.

1. Download the installer

Download the .pkg installation package from the official website.

2. Run the installer

Double-click the downloaded .pkg file and follow the installer's prompts to complete the installation.

The installer will automatically:

• Install Go to /usr/local/go (Intel Mac) or /opt/homebrew/opt/go (Apple Silicon Mac)
• Configure the necessary environment variables

3. Verify installation

Open a new terminal window and execute:

go version

If the installation is successful, you should see output similar to:

go version go1.21.3 darwin/arm64

Method 2: Using Archive Package

This method is suitable for users who need to manage multiple Go versions or install to a custom path.

1. Download the archive package

Download the .tar.gz compressed package from the official website.

2. Delete old version (if any)

sudo rm -rf /usr/local/go

3. Extract to /usr/local

sudo tar -C /usr/local -xzf go1.21.3.darwin-amd64.tar.gz

4. Configure environment variables

Add the following to your ~/.zshrc or ~/.bash_profile file:

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

5. Make environment variables take effect

For zsh (default shell in macOS Catalina and later):

source ~/.zshrc

For bash:

source ~/.bash_profile

6. Verify installation

go version

Method 3: Using Homebrew

If you use Homebrew package manager, you can install Go through Homebrew.

1. Install Go

brew install go

2. Verify installation

go version

3. Upgrade Go

brew upgrade go

Custom Installation Path

If you want to install Go to a custom path, you can:

1. Extract to custom directory

mkdir -p ~/go
tar -C ~/go -xzf go1.21.3.darwin-arm64.tar.gz

2. Configure environment variables

Add the following to your ~/.zshrc or ~/.bash_profile file:

export GOROOT=$HOME/go
export PATH=$PATH:$GOROOT/bin

3. Make environment variables take effect

source ~/.zshrc

Configure GOPATH

By default, Go uses $HOME/go as the workspace directory. If you want to use a different path, you can set the GOPATH environment variable:

export GOPATH=$HOME/gopath
export PATH=$PATH:$GOPATH/bin

Verify Installation

Create a simple Go program to verify that the installation is successful:

mkdir -p $HOME/hello
cd $HOME/hello
cat > hello.go << 'EOF'
package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}
EOF
go run hello.go

If the output is Hello, World!, it means the installation is successful.

Uninstall

Uninstall Installer Package Version

If you installed Go using the installer package, execute:

sudo rm -rf /usr/local/go

Or for Apple Silicon Mac:

sudo rm -rf /opt/homebrew/opt/go

Uninstall Homebrew Version

If you installed Go using Homebrew, execute:

brew uninstall go

Uninstall Custom Path Version

If you installed Go to a custom path, just delete the corresponding directory:

rm -rf ~/go

Then remove the Go-related environment variables from your ~/.zshrc or ~/.bash_profile file.

Troubleshooting

Command not found

If the go command is not found, please check:

1. Whether the PATH environment variable is configured correctly
2. Whether the environment variables have taken effect
3. Try to restart the terminal or re-login

Version mismatch

If the displayed version does not match the installed version, please check:

1. Whether there are multiple Go installations
2. Whether the PATH environment variable points to the correct Go installation directory
3. Execute which go to view the actual path of the go command

Permission denied

If you encounter a permission denied error, please use sudo to execute the command:

sudo tar -C /usr/local -xzf go1.21.3.darwin-arm64.tar.gz

Next Steps

After installation is complete, you can:

• Visit Go Getting Started Guide to learn Go language basics
• Visit Official Documentation for more detailed documentation
• Visit Go Tour to learn through interactive tutorials

Complete Example

After installing, use the program below to verify the toolchain from the command line. Copy it into a file and run go run main.go.

package main

import (
	"fmt"
	"os/exec"
	"runtime"
	"strings"
)

func main() {
	out, err := exec.Command("go", "version").Output()
	fmt.Println("go command found in PATH:", err == nil)
	fmt.Println("version output starts with go:", err == nil && strings.HasPrefix(string(out), "go"))
	fmt.Println("GOROOT is set:", runtime.GOROOT() != "")
}

Expected output:

go command found in PATH: true
version output starts with go: true
GOROOT is set: true

Common Pitfalls

• Pick the right installer. Apple Silicon (M-series) needs arm64; Intel Macs need x86-64.
• Do not mix the official pkg and Homebrew. Check which -a go and your PATH order (/usr/local/go/bin vs /opt/homebrew/bin).
• Edit ~/.zshrc, then reload it. Run source ~/.zshrc so the shell picks up the new path.
• cgo needs Xcode Command Line Tools. Plain Go builds do not, but packages that use cgo require them.
• To uninstall the official package, remove /usr/local/go and the PATH entry you added.

Change Log

• 2026-10-14: Added "Before You Start" notes, a complete runnable example with expected output, common pitfalls, and this change log.