Installation #

Installing Go is more than just downloading and running an installer. There are two environment concepts you need to understand — GOROOT and GOPATH — there’s a PATH configuration that has to be right so the go command works from anywhere, and there’s an editor setup that makes writing Go far more productive. This article walks you from zero to running your first Go program, explaining why each step matters.

Before You Start: Understand the Two Important Directories #

Go uses two directories with different roles, and understanding them before installing will prevent confusion later.

GOROOT is where Go itself is installed — it holds the compiler, the standard library, and all of Go’s built-in tools. It’s the equivalent of /usr/lib/jvm for Java or the Python directory at /usr/lib/python3.x. You never need to touch or modify this directory manually. GOROOT typically lives at /usr/local/go on Linux/macOS or C:\Go on Windows.

GOPATH is your personal workspace — where compiled artifacts, the module cache, and (in the old days before Go Modules) your project source code live. Its default is ~/go on Linux/macOS or C:\Users\<username>\go on Windows. Inside GOPATH there are three subdirectories:

~/go/
  ├── bin/   ← binaries from `go install` end up here
  │          (for example: gopls, staticcheck, dlv)
  ├── pkg/   ← compiled package cache and module cache
  └── src/   ← (old days) project source code lived here
              (now projects can live anywhere)

Since Go 1.11 introduced Go Modules, you no longer have to keep your projects inside GOPATH. Any directory can be a Go project as long as it contains a go.mod file. This is the modern, recommended way, and it’s what we’ll use throughout this series.

Installing on Windows #

Windows offers the .msi installer, which is the easiest option — the installer handles almost all of the PATH configuration automatically.

Step 1 — Download the official installer:

Open your browser and go to https://go.dev/dl/. You’ll see the list of available Go versions. Download the file named go1.x.x.windows-amd64.msi for 64-bit systems (almost all modern computers). If you’re on Windows on ARM (like a Surface laptop with an ARM chip), download the windows-arm64 version instead.

Step 2 — Run the installer:

Open the downloaded .msi file. The installation wizard opens. Click Next, leave the default installation location at C:\Go (strongly advised not to change this), keep clicking Next and then Install. The installer automatically adds C:\Go\bin to the system PATH.

Step 3 — Open a new terminal:

Important: after installation finishes, you must open a new Command Prompt or PowerShell window. A terminal that was already open before the install won’t pick up the PATH change.

Step 4 — Verify the installation:

go version

Expected output:

go version go1.23.0 windows/amd64

Step 5 — Add GOPATH/bin to PATH (optional but recommended):

Binaries you install with go install (like gopls or staticcheck) are stored in %USERPROFILE%\go\bin. To call them from anywhere, add it to PATH:

  • Open Control Panel → System → Advanced System Settings → Environment Variables
  • Under User variables, find the Path variable and click Edit
  • Add a new entry: %USERPROFILE%\go\bin
  • Click OK and open a new terminal to apply the change

Windows troubleshooting:

If go version shows the error 'go' is not recognized as an internal or external command, likely causes are:

  • The terminal wasn’t restarted after installation
  • The installer failed to add PATH — check manually whether C:\Go\bin is in the System Path
  • An older Go installation is conflicting — uninstall it via Control Panel before reinstalling

Installing on macOS #

macOS has two equally valid installation options. Use the .pkg installer if you don’t use Homebrew, or Homebrew if you already use it for other tools.

Option A: Official .pkg Installer #

Step 1 — Identify your chip architecture:

Before downloading, determine your Mac’s chip type:

  • Intel (2019 and earlier) → download go1.x.x.darwin-amd64.pkg
  • Apple Silicon M1/M2/M3 (2020 and later) → download go1.x.x.darwin-arm64.pkg

If you’re unsure, open the Apple menu → About This Mac and check the Chip or Processor section.

Step 2 — Run the installer:

Open the downloaded .pkg file and follow the wizard to completion. Go is installed to /usr/local/go.

Step 3 — Add Go to PATH:

Open a terminal and run the following commands based on the shell you use:

# Check your active shell
echo $SHELL
# If the output is: /bin/zsh → use ~/.zshrc
# If the output is: /bin/bash → use ~/.bash_profile

For zsh (the default since macOS Catalina):

echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc
source ~/.zshrc

For bash:

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

Option B: Homebrew #

If you already use Homebrew as your macOS package manager, this is the most practical way:

brew install go

Homebrew automatically handles installing to the right location and adding Go to PATH. To upgrade to a new version later:

brew upgrade go

Verification:

go version
# Output: go version go1.23.0 darwin/arm64

go env GOROOT
# Output: /usr/local/go (or /opt/homebrew/opt/go/libexec for Homebrew)

go env GOPATH
# Output: /Users/username/go

Installing on Linux #

Linux doesn’t provide a GUI installer — everything is done via the terminal. The process is the same for Ubuntu, Debian, Fedora, Arch, and other distros.

Manual Method (Recommended — Always the Latest Version) #

Step 1 — Find the latest version:

Visit https://go.dev/dl/ in your browser to see the latest version, or run:

# Check the latest version via the API
curl -s https://go.dev/VERSION?m=text

Step 2 — Download the tarball:

# Replace 1.23.0 with the latest version
VERSION="1.23.0"
ARCH="amd64"  # change to arm64 for Raspberry Pi or ARM servers

wget "https://go.dev/dl/go${VERSION}.linux-${ARCH}.tar.gz"

Step 3 — Remove the old installation and extract:

# Remove the old installation (IMPORTANT: don't skip this step when upgrading)
sudo rm -rf /usr/local/go

# Extract to /usr/local
sudo tar -C /usr/local -xzf "go${VERSION}.linux-${ARCH}.tar.gz"

# Verify
ls /usr/local/go/bin/
# Should contain: go  gofmt
Always remove /usr/local/go before extracting a new version. If you extract without deleting first, files from the old version can mix with the new one and cause unpredictable behavior that’s very hard to debug.

Step 4 — Add Go to PATH:

# Add to ~/.profile (applies to all login shells)
cat >> ~/.profile << 'EOF'

# Go installation
export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$HOME/go/bin
EOF

# Apply the change
source ~/.profile

Or if you use .bashrc or .zshrc:

# For bash
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

Via Package Manager (Ubuntu/Debian) #

Avoid sudo apt install golang — the packages in Ubuntu/Debian repositories are often several versions behind. The manual method above always gives you the latest version with security updates.

If you still prefer apt, add the official PPA:

sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt update
sudo apt install golang-go

Via Snap #

sudo snap install go --classic

Snap always provides the latest version, but it has some filesystem access limitations that can occasionally cause issues.

Verification on Linux:

go version
# Output: go version go1.23.0 linux/amd64

# Check all Go environment variables
go env

Understanding the go env Output #

The go env command prints all of Go’s environment variables. It’s extremely useful for troubleshooting:

go env

Key output to pay attention to:

GOROOT="/usr/local/go"         ← Go installation location
GOPATH="/home/username/go"     ← Go workspace
GOBIN=""                       ← if set, go install binaries go here
GOMODCACHE="/home/username/go/pkg/mod"  ← module cache
GOPROXY="https://proxy.golang.org,direct"  ← module proxy
GOOS="linux"                   ← current target OS
GOARCH="amd64"                 ← current target architecture
CGO_ENABLED="1"                ← whether CGO is enabled

Editor Setup: VS Code #

VS Code is the most popular editor for Go thanks to the official extension maintained directly by the Go team at Google. This extension provides autocompletion via gopls, linting via staticcheck, debugging via dlv, and much more.

Step 1 — Install VS Code:

Download it from https://code.visualstudio.com and install it for your platform.

Step 2 — Install the Go extension:

Open VS Code and press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS) to open the Extensions panel. Search for Go and install the extension published by Go Team at Google.

Step 3 — Install Go tools:

The first time you open a .go file, VS Code shows a notification in the bottom right: “The ‘gopls’ language server is not installed. Install it?” or “Some Go tools are missing.” Click Install All to install all the tools at once.

Alternatively, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Go: Install/Update Tools, select everything, and click OK.

The tools installed and what they do:

gopls        ← Language server: autocompletion, go-to-definition,
               find references, refactoring
staticcheck  ← Comprehensive linter: detects bugs, code smells,
               and performance issues
dlv          ← Delve debugger: breakpoints, variable inspection,
               step debugging
goimports    ← Formatter + auto-import: adds needed imports and
               removes unused ones
gotest       ← Test runner with better output

Step 4 — Recommended configuration:

Open Settings (Ctrl+, / Cmd+,) and add or enable:

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": "explicit"
    },
    "[go]": {
        "editor.defaultFormatter": "golang.go"
    },
    "go.lintTool": "staticcheck",
    "go.lintOnSave": "package"
}

This configuration ensures your Go code is automatically formatted and imports are cleaned up every time you save.

Alternative: GoLand (JetBrains) #

GoLand is JetBrains’ commercial IDE dedicated to Go. Unlike VS Code, which needs an extension, GoLand has all Go features integrated from the start — more opinionated but zero-configuration. A good fit if you’re already used to IntelliJ IDEA or PyCharm. It offers a 30-day free trial, then becomes paid.

Your First Project with Go Modules #

Now it’s time to create and run your first Go program using the modern system — Go Modules.

Step 1 — Create a project directory:

mkdir hello-go
cd hello-go

Step 2 — Initialize a Go Module:

go mod init hello-go

This command creates a go.mod file that defines the module name and the minimum Go version:

module hello-go

go 1.23

Module names usually follow the domain/repo format for published projects, for example github.com/username/hello-go. For local projects, a simple name like hello-go is enough.

Step 3 — Create the main.go file:

package main

import (
    "fmt"
    "runtime"
)

func main() {
    fmt.Println("Hello, Go!")
    fmt.Printf("Go version: %s\n", runtime.Version())
    fmt.Printf("OS: %s, Arch: %s\n", runtime.GOOS, runtime.GOARCH)
}

Step 4 — Run it:

go run main.go

Expected output:

Hello, Go!
Go version: go1.23.0
OS: linux, Arch: amd64

Step 5 — Build a binary:

go build -o hello-go .

# Run the resulting binary
./hello-go        # Linux/macOS
.\hello-go.exe    # Windows

Essential go CLI Commands #

Go provides a single tool (go) for almost every development need. Here are the most frequently used commands:

The key differences in a program’s lifecycle using go run, go build, and go install can be visualized in the following diagram:

flowchart TD
    Source["Source Code (.go)"] --> Run["go run"]
    Source --> Build["go build"]
    Source --> Install["go install"]

    Run --> TempBin["Temporary Binary (Temp Directory)"]
    TempBin --> RunExec["Run & Show Output"]
    
    Build --> LocalBin["Local Executable Binary (Working Directory)"]
    LocalBin --> ManualExec["Run Manually (./app)"]
    
    Install --> PathBin["Executable Binary in GOPATH/bin"]
    PathBin --> GlobalExec["Run Globally from Terminal"]
# Run a program directly without creating a binary
go run main.go
go run .          # run all .go files in the current directory

# Create an executable binary
go build .                    # binary named after the module
go build -o binary-name .     # specify the binary name

# Cross-compilation
GOOS=linux GOARCH=amd64 go build -o app-linux .
GOOS=windows go build -o app.exe .
GOOS=darwin GOARCH=arm64 go build -o app-mac .

# Dependency management
go mod init module-name        # initialize a new module
go mod tidy                    # remove unused dependencies, download missing ones
go get github.com/gin-gonic/gin@latest  # add a new dependency
go get github.com/gin-gonic/[email protected]  # add a specific version

# Testing
go test ./...                  # run all tests
go test -v ./...               # verbose output
go test -run TestFunctionName  # run a specific test
go test -cover ./...           # view test coverage

# Formatting and linting
go fmt ./...                   # format all Go files
go vet ./...                   # check for common mistakes

# Install tools
go install golang.org/x/tools/gopls@latest  # install gopls
go install honnef.co/go/tools/cmd/staticcheck@latest  # install staticcheck

# Documentation
go doc fmt.Println             # view function documentation
go doc -all fmt                # view all package documentation

Installation Verification Checklist #

Use this checklist to make sure everything works correctly before moving on to the next article:

BASIC VERIFICATION:
  □ go version  → prints the correct Go version
  □ go env GOROOT  → points to the Go installation directory
  □ go env GOPATH  → points to ~/go (Linux/macOS) or C:\Users\<user>\go (Windows)

PATH VERIFICATION:
  □ which go  (Linux/macOS) or where go  (Windows) → finds the go binary
  □ ~/go/bin or %USERPROFILE%\go\bin is on PATH  → so go install tools can be called

PROJECT TEST:
  □ go mod init test-project  → creates go.mod without errors
  □ go run main.go  → runs the program without errors
  □ go build .  → produces a binary without errors

EDITOR:
  □ VS Code opens .go files with syntax highlighting
  □ Autocompletion works (type `fmt.` and wait for suggestions)
  □ Format on save works (add extra spaces, save, and see if it cleans itself up)

Summary #

  • GOROOT is the Go installation location — don’t modify it manually; it contains the compiler and standard library.
  • GOPATH (default ~/go) contains the module cache (pkg/) and binaries from go install (bin/).
  • Always download from go.dev/dl/ — Linux distro package managers are often several versions behind.
  • Windows: the .msi installer handles PATH automatically; always open a new terminal after installing.
  • macOS: use the official .pkg or Homebrew; add /usr/local/go/bin and $HOME/go/bin to PATH.
  • Linux: the manual tarball method always gives the latest version; remove /usr/local/go first before upgrading.
  • Go Modules (go mod init) is the modern way to manage projects — no need to store them in GOPATH anymore.
  • VS Code + the golang.go extension + Install All tools is the fastest, most complete editor setup.
  • Verify your installation with go version, go env, and running a simple program.

← Previous: Introduction   Next: Core Syntax →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact