CHAPTER 03 · FOUNDATIONS

Installing Go & Setting Up Your Editor

The fastest way to learn Go is to run Go. This chapter gets a working compiler on your machine and an editor configured so you get autocomplete, jump-to-definition, and error squiggles as you type.

If you'd rather not install anything yet, every snippet in this course has an Open Go Playground button that copies the code and opens the Go Playground in a new tab. But for chapters 4 onward you'll get more out of running things locally, and a 2-minute install pays back forever.

Learning objectives

  • Install Go on macOS, Linux, or Windows.
  • Verify the install with go version.
  • Configure VS Code (or an editor of your choice) with the Go extension and gopls.
  • Understand the difference between the legacy GOPATH workflow and modern Go modules, and know that you only need modules.

Download Go

The official downloads live at go.dev/dl. As of writing, the current release is in the 1.22+ family. Always grab the latest stable release unless you have a specific reason not to, Go's compatibility promise (Chapter 2) means newer versions don't break your existing code.

You have three broad install paths:

  • Official installer: the recommended default, especially on macOS and Windows.
  • Package manager: Homebrew (macOS), apt/snap/dnf (Linux), winget/Chocolatey (Windows). Convenient if you already use one.
  • Manual tarball: most common on Linux.

Pick the one that matches your platform below.

Install by operating system

macOS

Option A, Homebrew (recommended if you have it):

brew install go

Option B, Official installer:

  1. Download the .pkg file for macOS from go.dev/dl.
  2. Double-click and follow the prompts. The installer puts Go at /usr/local/go and adds /usr/local/go/bin to your PATH.
  3. Open a fresh terminal so the new PATH is loaded.

Linux

Option A, Distro package manager (often older but easiest):

# Debian / Ubuntu
sudo apt update && sudo apt install golang-go

# Fedora
sudo dnf install golang

# Arch
sudo pacman -S go

Option B, Official tarball (recommended for the latest version):

# 1. Download, substitute the version you want
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz

# 2. Remove any previous Go install and unpack to /usr/local
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz

# 3. Add Go to your PATH (append to ~/.bashrc or ~/.zshrc)
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

Windows

Option A, winget (Windows 10+):

winget install -e --id GoLang.Go

Option B, Official installer:

  1. Download the .msi from go.dev/dl.
  2. Run it and accept the defaults. Go installs to C:\Program Files\Go and is added to PATH.
  3. Important: close and reopen any terminal windows so they pick up the new PATH.

If you're a WSL2 user, install Go inside WSL using the Linux instructions above, that's almost always the better experience.

Verify the install

Open a brand-new terminal and run:

go version

You should see something like:

go version go1.22.0 darwin/arm64

That confirms the binary is on your PATH and reports its OS/architecture. To see Go's full environment configuration:

go env

You don't need to memorize any of those values. The two worth recognizing early are GOROOT (where Go itself lives) and GOPATH (where Go puts downloaded modules and installed binaries, defaults to ~/go).

Set up your editor

Go has a language server called gopls (pronounced "go please"). With a single click, it gives you autocomplete, go-to-definition, find references, rename, hover docs, live error diagnostics, and automatic formatting on save. Use it. Coding without it is needlessly hard.

VS Code (recommended for beginners)

  1. Install VS Code.
  2. Open Extensions and install the official Go extension by Google.
  3. Open any .go file. VS Code will prompt you to install the required tools (gopls, dlv for debugging, staticcheck, etc). Click Install All.
  4. Done. Start typing.

Other editors

  • GoLand by JetBrains, paid, heavyweight, but excellent.
  • Neovim: install gopls with go install golang.org/x/tools/gopls@latest, then configure your LSP plugin (e.g. nvim-lspconfig) to use it.
  • Zed / Sublime / Helix: all support gopls via their LSP integrations.
✓
Format on save, turn it on Configure your editor to run gofmt (or goimports) on every save. Code in this course assumes consistent formatting. The VS Code Go extension does this by default.

GOPATH vs Go modules

You'll see references to GOPATH in older blog posts. Here's the short version so you can ignore it:

  • Pre-2018: all your Go code had to live inside a specific directory tree ($GOPATH/src/github.com/you/...). Painful and limiting.
  • 2018+: Go modules. Run go mod init in any directory and that directory becomes a Go project. Full stop. You can keep your code anywhere on disk.

Modern Go is module-based. We'll use go mod init in Chapter 4. You can pretend GOPATH doesn't exist (it does, but only as a cache for downloaded dependencies and installed tools).

!
Old tutorials trap If a tutorial tells you to put your code under ~/go/src/something for it to "work", that tutorial is from before 2018. Skip it. Modern Go just needs a directory with a go.mod file in it.

Troubleshooting

SymptomLikely cause & fix
command not found: go Go's bin directory isn't on your PATH. Re-check the install steps for your OS, then open a new terminal.
Wrong version reported You probably have two installs (e.g. brew + manual). which go tells you which one is being used. Remove the old one.
VS Code says "Failed to install gopls" Make sure $GOPATH/bin (defaults to ~/go/bin) is on your PATH. Then run Go: Install/Update Tools from the command palette.
"GOPATH not set" warnings on Linux Modern Go sets a sensible default (~/go). You can ignore this warning, or explicitly export GOPATH=$HOME/go in your shell rc.

Check your understanding

Practice exercises

EXERCISE 1

Verify your toolchain

From a fresh terminal, run all three commands below. They should all work without errors.

go version
go env GOPATH
go env GOROOT

Note the values of GOPATH and GOROOT. You won't usually need to think about them, but it's good to know where Go puts things.

Expected output (yours will differ in version & paths) 
$ go version
go version go1.22.0 darwin/arm64

$ go env GOPATH
/Users/you/go

$ go env GOROOT
/opt/homebrew/Cellar/go/1.22.0/libexec
EXERCISE 2

Configure your editor

Install your editor of choice (VS Code if undecided), the Go extension, and let it install gopls and friends. Then open an empty .go file and confirm:

  • Typing fmt. shows autocomplete suggestions.
  • Saving the file auto-formats it.
  • Hovering a function name shows its documentation.

If any of those don't work, you'll save yourself a lot of pain later by debugging it now.

If something's off
  • Open the command palette and run Go: Install/Update Tools, select all, and reinstall.
  • Make sure your editor is opening a folder, not a single file, gopls needs project context.
  • Confirm ~/go/bin (or whatever go env GOPATH's value is + /bin) is on your PATH.

Further reading

Toolchain ready?