Install Go 1.27 and set up your editor

Installing Go takes one download of 60 to 70 MB from go.dev, and it is finished when one command, go version, prints the release you installed. Most trouble comes later, from a second Go installation or a setting left behind by an old one, so this lesson does more than install: it shows where Go keeps everything and reproduces the two problems that break builds after an upgrade.

You will install Go 1.27 on Windows, macOS or Linux, read the folders Go uses with go env, change a setting and undo it, connect an editor through gopls, choose what telemetry may do, and fix an older Go that comes first on PATH and a stale GOROOT.

One download puts the whole toolchain in one folder

The downloads page, go.dev/dl, offers one file per system: an installer for macOS (.pkg) and Windows (.msi), and an archive (.tar.gz) for Linux, each for amd64 or arm64 processors. Take the newest minor release of 1.27, such as 1.27.2, because minor releases carry the security fixes. The examples on this track show what Go 1.27.1 printed.

• macOS. Open the package and follow the prompts. It installs Go into /usr/local/go and puts /usr/local/go/bin on your PATH by creating the file /etc/paths.d/go. Go 1.27 needs macOS 13 Ventura or later.
• Windows. Open the MSI file and follow the prompts. By default it installs into Program Files. Close every open command prompt and open a new one, so the changes the installer made to the environment take effect.
• Linux. Extract the archive into /usr/local, after removing any older tree. Step through the official commands:

On every system the check is the same, and it should be the first thing you run in a new terminal:

from session import run

# The first check after any install: which Go runs, for which system.
run("""
go version
go env GOVERSION GOOS GOARCH
""")

$ go version
go version go1.27.1 darwin/arm64
$ go env GOVERSION GOOS GOARCH
go1.27.1
darwin
arm64

go version names the release and the system it was built for, here go1.27.1 on darwin/arm64, a Mac with Apple silicon. go env prints any of the go command’s settings by name: GOVERSION is the release again, and GOOS and GOARCH are the operating system and processor that go build targets unless you say otherwise.

go env shows where Go keeps everything

The installation folder is GOROOTGOROOT: The folder of a Go installation, which holds the go command, the compiler and the standard library. The go command finds it from its own location, so it rarely needs setting by hand.: /usr/local/go after the official macOS and Linux installs. It holds the go command, the compiler and the standard library, and the go command works it out from its own location, so you never need to set it. Everything else Go writes lives in folders that go env reports:

from session import run

# Where this Go keeps installed commands, downloaded modules and its build cache,
# and the settings it uses to download modules.
run("""
go env GOPATH GOBIN GOMODCACHE GOCACHE
go env GOPROXY GOSUMDB GOTOOLCHAIN
""")

$ go env GOPATH GOBIN GOMODCACHE GOCACHE
~/go
~/go/bin
~/go/pkg/mod
~/Library/Caches/go-build
$ go env GOPROXY GOSUMDB GOTOOLCHAIN
https://proxy.golang.org,direct
sum.golang.org
auto

• GOPATHGOPATH: A folder, by default go in your home folder, under which the go command keeps downloaded modules (pkg/mod) and the commands go install builds (bin), unless GOMODCACHE or GOBIN name other folders. is ~/go, a folder named go in your home folder, unless you set it. With modules it no longer says where your code lives; it is the parent of two folders the go command fills.
• GOBIN, ~/go/bin, is where go install writes the commands it builds. Add it to PATH, as the install instructions say, with export PATH="$PATH:$(go env GOPATH)/bin" in your shell profile on macOS or Linux. Go 1.27.1 prints the folder it will use even when GOBIN is not set.
• GOMODCACHE, ~/go/pkg/mod, is the module cachemodule cache: The folder named by GOMODCACHE where the go command keeps every module version it has downloaded, so each version is downloaded once and shared by all your projects.: every module version the go command has downloaded, shared by all your projects.
• GOCACHE is the build cachebuild cache: The folder named by GOCACHE where the go command keeps compiled packages and the programs go run built, so a later build reuses that work instead of compiling again. of compiled packages, in your user cache folder: ~/Library/Caches/go-build on macOS, ~/.cache/go-build on Linux and %LocalAppData%\go-build on Windows.
• GOPROXY and GOSUMDB say where modules come from and how they are checked: the module proxymodule proxy: A server that hands out module versions to the go command. GOPROXY lists the proxies to ask, in order; the default asks proxy.golang.org first and then the module's own source (direct). proxy.golang.org, then the module’s own repository (direct), with every download checked against the checksum database sum.golang.org. GOTOOLCHAIN auto lets a module’s go line fetch a newer Go when it needs one.

Step through one go install and watch which of these settings decides each part of it:

A setting comes from the environment, your go env file or the installation

You will sometimes need to change one of these settings, for one command or for good. The session changes GOPROXY in both ways and then undoes the change:

from session import run

# Change a setting with go env -w, override it for one command, then undo it.
run("""
go env GOPROXY
go env -w GOPROXY=direct
go env GOPROXY
go env -changed
GOPROXY=off go env GOPROXY
go env -u GOPROXY
go env GOPROXY
""")

$ go env GOPROXY
https://proxy.golang.org,direct
$ go env -w GOPROXY=direct
$ go env GOPROXY
direct
$ go env -changed
GOPROXY='direct'
$ GOPROXY=off go env GOPROXY
off
$ go env -u GOPROXY
$ go env GOPROXY
https://proxy.golang.org,direct

go env -w GOPROXY=direct changed the setting for every later command, and go env -changed listed it. Writing GOPROXY=off in front of one command changed it for that command alone, and go env -u GOPROXY removed the saved value, so the default came back. Those three places, and a fourth, are read in a fixed order:

The order explains a common surprise: a value saved with go env -w seems to be ignored, because an environment variable of the same name, set in a shell profile long ago, wins over it. go env -changed lists the settings that differ from the defaults, whether they come from the environment or from your go env file, which makes it the first command to run when Go behaves differently on two machines.

Your editor talks to gopls, the Go language server

Most of what makes an editor good at Go comes from goplsgopls: Go's official language server, pronounced "Go please". Editors send it your code and get back completions, errors as you type, formatting, renames and the other features of a Go editor., the official language server of the Go team. Editors talk to it through the Language Server Protocol, a standard that many editors support, so the same completions, errors and refactorings appear in VS Code, Vim and Neovim, Emacs, Helix, Zed or Sublime Text. Step through one file being opened, edited and saved:

In the 2025 Go Developer Survey, most respondents preferred VS Code (37 %) or GoLand (28 %); Zed and Cursor were each the preferred editor of 4 %. How you set up the two leading ones:

• VS Code. Install the Go extension (its identifier is golang.go), then open any .go or go.mod file to activate it. The extension depends on go and gopls, and if gopls is missing it tries to install it; the command Go: Install/Update Tools installs and updates the other tools it uses. A ⚡ sign next to the Go version in the status bar says the language server is running. The extension needs Go 1.21 or newer and officially supports the two most recent major releases.
• GoLand. JetBrains’ IDE for Go usually sets GOROOT by itself, and it can also download a Go SDK for you: open Settings, then Go | GOROOT.

Another editor needs an LSP plugin and gopls itself, installed with go install golang.org/x/tools/gopls@latest; the program lands in GOBIN, as the scene in the go env section showed. gopls follows the Go release policy: it supports the go command of the two most recent major releases, so keep Go up to date along with it.

Telemetry stays on your computer unless you switch uploading on

Since Go 1.23 the toolchain keeps telemetry counters, small counts of named events in its own programs, and the go telemetry command decides what happens to them:

from session import run

# The telemetry mode: local is the default; off stops even local counting.
run("""
go telemetry
go telemetry off
go telemetry
go telemetry local
go env GOTELEMETRY
""")

$ go telemetry
local
$ go telemetry off
$ go telemetry
off
$ go telemetry local
$ go env GOTELEMETRY
local

The counters are kept in your user configuration folder, under go/telemetry, and go env GOTELEMETRYDIR prints where. The Go telemetry documentation says that even the counters that record a call stack hold only the names and line numbers of functions in the toolchain’s own programs, never the names or contents of your source code. Turning uploading on is your choice: go telemetry on does it, and so does answering yes to the prompt gopls may show in VS Code. go telemetry off stops even the local counting, and go telemetry local returns to the default, as the session did.

Two Go installations in each other’s way

Many problems after an upgrade come from two installations meeting. The session reproduces four of them on one computer, which has Go 1.27.1 and also an older Go 1.26.8:

// hello.go: a one-line program to test that a Go installation can build.
package main

import "fmt"

func main() {
	fmt.Println("built with a working GOROOT")
}

from session import run

# Four ways two Go installations get in each other's way, then the build that works.
run(
    """
# 1. An older Go comes first on PATH ($OLD_GO_BIN holds Go 1.26.8):
PATH="$OLD_GO_BIN:$PATH" go version
# 2. GOROOT, set by hand, still names the older release's folder:
GOROOT="$OLD_GOROOT" go build -o hello hello.go 2>&1 | grep -m 1 "does not match"
GOROOT="$OLD_GOROOT" go env -changed
# 3. GOROOT names a folder that no longer exists:
GOROOT="$HOME/sdk/go1.20" go version
# 4. Go 1.27.1 refuses to save GOROOT, Go 1.26.8 still saves it, and Go 1.27.1 reads it:
go env -w GOROOT="$OLD_GOROOT"
"$OLD_GO_BIN/go" env -w GOROOT="$OLD_GOROOT"
go build -o hello hello.go 2>&1 | grep -m 1 "does not match"
go env -changed
go env -u GOROOT
go env GOENV
"$OLD_GO_BIN/go" env -u GOROOT
# With neither setting, the same build works:
go build -o hello hello.go && ./hello
""",
    expect_failure=[
        'GOROOT="$HOME/sdk/go1.20" go version',
        'go env -w GOROOT="$OLD_GOROOT"',
        "go env -u GOROOT",
    ],
)

# 1. An older Go comes first on PATH ($OLD_GO_BIN holds Go 1.26.8):
$ PATH="$OLD_GO_BIN:$PATH" go version
go version go1.26.8 darwin/arm64
# 2. GOROOT, set by hand, still names the older release's folder:
$ GOROOT="$OLD_GOROOT" go build -o hello hello.go 2>&1 | grep -m 1 "does not match"
compile: version "go1.26.8" does not match go tool version "go1.27.1"
$ GOROOT="$OLD_GOROOT" go env -changed
# 3. GOROOT names a folder that no longer exists:
$ GOROOT="$HOME/sdk/go1.20" go version
go: cannot find GOROOT directory: ~/sdk/go1.20
[exit status 2]
# 4. Go 1.27.1 refuses to save GOROOT, Go 1.26.8 still saves it, and Go 1.27.1 reads it:
$ go env -w GOROOT="$OLD_GOROOT"
go: GOROOT cannot be modified
[exit status 1]
$ "$OLD_GO_BIN/go" env -w GOROOT="$OLD_GOROOT"
$ go build -o hello hello.go 2>&1 | grep -m 1 "does not match"
compile: version "go1.26.8" does not match go tool version "go1.27.1"
$ go env -changed
$ go env -u GOROOT
go: GOROOT cannot be modified
[exit status 1]
$ go env GOENV
~/Library/Application Support/go/env
$ "$OLD_GO_BIN/go" env -u GOROOT
# With neither setting, the same build works:
$ go build -o hello hello.go && ./hello
built with a working GOROOT

The first go version printed go1.26.8, although 1.27.1 is installed, because the older Go’s folder came first on PATH. The second command failed with compile: version "go1.26.8" does not match go tool version "go1.27.1": GOROOT, set by hand, made the new go command run the old compiler, and go env -changed did not list it. The third failed before building anything, because GOROOT named a folder that no longer exists.

The fourth case is the one an upgrade leaves behind. Go 1.27.1 refused go env -w GOROOT=…, but Go 1.26.8 saved the same value in the go env file without a word, and from then on Go 1.27.1 read it there and failed with the same mismatch, while go env -changed printed nothing. It could not remove the line either: go env -u GOROOT gave GOROOT cannot be modified too, and only the older go command took it out again.

Step through how a typed go command reaches its compiler, and where each failure enters:

To find the cause on your own computer, list every go the shell can find with which -a go on macOS and Linux, or where go on Windows, and print the GOROOT variable with echo $GOROOT (echo %GOROOT% in the Windows command prompt). A stale value comes from the environment, through a shell profile, the Windows environment variables or an editor’s own setting, or from a GOROOT line in the go env file. go env -changed lists neither, so look in both places.

Once both are clean, the two answers agree: go version names the release of the go command that runs, and go env GOROOT names the folder it came from.

Practise: check your own installation

Run these in a new terminal and compare each line with what this lesson showed:

1. go version prints go1.27 followed by a minor release, and your system.
2. which -a go (or where go on Windows) prints one line, the folder of that installation.
3. go env GOROOT prints that installation’s folder, echo $GOROOT prints an empty line (on macOS and Linux), and the file that go env GOENV names, if there is one, has no GOROOT line.
4. go env GOPATH GOBIN GOMODCACHE print folders under your home folder, and GOBIN is on your PATH.
5. go env -changed prints only settings you changed on purpose.

Then answer the self-check on the six ideas of this lesson; it begins with the idea you are least sure of:

Interview questions

Warm-up (fresher): What is GOPATH used for in a project that uses modules?

With modules, your code can live in any folder, so GOPATH no longer says where projects go. It is the default home of two things: the module cache in GOPATH/pkg/mod, where downloaded module versions are kept, and GOPATH/bin, where go install puts the commands it builds. GOMODCACHE and GOBIN can move each of them elsewhere. When GOPATH is not set, it is a folder named go in your home folder ($HOME/go on Unix, %USERPROFILE%\go on Windows), so most people never set it, and go env GOPATH prints the value in use. GOPATH also has an older role, GOPATH mode, the way projects from before modules are built, which the go command uses only when modules are turned off. A new project needs none of it.

Two longer interview questions of this module start from this lesson:

Key takeaways

• An installer (macOS, Windows) or a fresh archive in /usr/local (Linux) puts the whole toolchain in one folder, and go version in a new terminal must print the release you installed.
• go env reports where Go keeps things: GOPATH (~/go), GOBIN (~/go/bin, which belongs on PATH), the module cache (~/go/pkg/mod) and the build cache, and where modules come from (GOPROXY, GOSUMDB).
• A setting comes from the environment first, then your go env file (go env -w, go env -u), then the installation’s go.env, then the built-in default; go env -changed shows what differs.
• Editors get completion, errors as you type, formatting and import fixes from gopls; VS Code’s Go extension installs it, and GoLand finds or downloads a Go SDK itself.
• Telemetry is local by default: counters stay on your computer, go telemetry on lets a sample of them be uploaded, and go telemetry off stops counting.
• An older Go first on PATH and a GOROOT set by hand, in the environment or in a go env file an older Go wrote, are the classic install problems; keep one Go on PATH and leave GOROOT unset.