Install Go and Set Up Your Development Environment

A correct installation and a well‑configured environment are the foundation for productive Go development. Go’s toolchain is deliberately simple: a single binary distribution that includes the compiler, standard library, and essential tools. This guide walks you through installing the latest stable Go release on Windows, macOS, and Linux, and then setting up a professional workspace that follows modern, module‑based conventions.

Once you complete this article, you will have a working Go environment, a capable editor, and a clear understanding of the tools that will accompany you through every stage of the handbook.

Choose the Right Go Version

For learning and for most production projects, use the latest stable release of Go. Stable releases receive security patches and bug fixes, and they represent the version that the broader ecosystem targets.

• Stable releases (e.g. go1.23.0) – recommended for all development.
• Release candidates – suitable only when you need to test upcoming language features or verify compatibility ahead of a release.
• Development snapshots – intended for Go contributors; avoid them for daily work.

Unless your project explicitly pins an older version, always start with the latest stable release. You can manage multiple Go versions side‑by‑side with tools like go install golang.org/dl/go1.22@latest if needed, but a single, up‑to‑date installation is sufficient for this learning path.

Download and Install Go

Windows

1. Download the MSI installer from the official Go downloads page.
2. Run the installer and accept the default installation path (typically C:\Program Files\Go or C:\Go). The installer automatically adds Go\bin to your system PATH.
3. Restart any open command prompts or terminals so the new PATH takes effect.

To verify, open a new Command Prompt or PowerShell window and run:

go version

You should see output similar to go version go1.23.0 windows/amd64.

macOS

You have two solid options:

Official installer

1. Download the macOS .pkg installer.
2. Run the installer; it places Go in /usr/local/go and adds /usr/local/go/bin to your PATH.
3. Open a new terminal and verify with go version.

Homebrew

If you already use Homebrew, install Go with:

brew install go

Homebrew keeps Go updated alongside the rest of your packages. Both methods are equally supported; choose whichever fits your workflow.

Linux

The recommended approach is to use the official binary tarball. This keeps you independent of distribution package managers that sometimes lag behind.

1. Download the Linux tarball for your architecture (e.g. go1.23.0.linux-amd64.tar.gz).
2. Remove any previous Go installation at /usr/local/go and extract the tarball:

sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz

3. Add /usr/local/go/bin to your PATH by appending the following line to ~/.profile or ~/.bashrc:

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

4. Reload your profile (source ~/.profile) and verify with go version.

For Ubuntu, Debian, Fedora, or Arch, you may also use the distribution packages (apt, dnf, pacman), but be aware they may not provide the very latest stable release immediately. The official tarball guarantees you have the version you expect.

Verify the Installation

Beyond checking the version, confirm your environment is correctly configured:

go env

This prints all Go environment variables. Verify that:

• GOROOT points to your Go installation (e.g. /usr/local/go).
• GOPATH defaults to $HOME/go (you do not need to change this for modern modules‑based work).
• GOBIN is empty or points to a directory in your PATH if you plan to install binaries with go install.

If go version works and go env reports sensible paths, your installation is healthy.

Understanding Go Environment Variables

Modern Go development relies on a few key variables. You rarely need to adjust them manually, but knowing what they mean helps with debugging.

Variable	Purpose
GOROOT	The directory where Go is installed. The compiler and standard library live here.
GOPATH	The workspace directory used by older GOPATH‑based workflows. Defaults to $HOME/go.
PATH	Must include $GOROOT/bin (and optionally $GOPATH/bin) so the go command is available.
GOMODCACHE	The location of the module cache (downloaded dependencies). Defaults to $GOPATH/pkg/mod.
GOCACHE	Cache for build and test results to speed up subsequent runs.

In a modules‑based project, you do not need to place your code inside GOPATH. You are free to create projects anywhere on your filesystem.

Install a Professional IDE

Visual Studio Code

VS Code with the official Go extension provides a first‑class development experience. After installing VS Code, add the Go extension (golang.go). When you open a Go file for the first time, the extension will prompt you to install the required tools (language server, debugger, linters). Accept all suggestions.

Key features:

• Intelligent autocompletion via gopls, the Go language server.
• Integrated debugging with breakpoints, variable inspection, and call stacks.
• Formatting with gofmt on save.
• Static analysis with go vet and additional linters.

VS Code is free, cross‑platform, and used by a large portion of the Go community. It is the recommended starting point for this handbook.

GoLand

GoLand by JetBrains is a commercial, full‑featured IDE designed specifically for Go. It offers deep code inspection, advanced refactoring, database tools, and tight integration with version control. GoLand is an excellent choice for professional teams who prefer a dedicated, out‑of‑the‑box experience.

Both editors serve professional developers well. Choose the one that fits your workflow; the rest of this handbook is editor‑agnostic.

Configure Development Tools

Go ships with a rich set of command‑line tools. Familiarise yourself with these five; you will use them constantly.

• gofmt – formats Go code according to the canonical style. Your editor can run it on save, ensuring every file follows the same conventions.
• go vet – performs static analysis to catch suspicious constructs, such as unreachable code or mismatched printf verbs.
• go test – runs tests and benchmarks. The foundation of confident, repeatable verification.
• go mod – manages module dependencies (go mod init, go mod tidy, go mod download).
• go doc – extracts documentation from source code and displays it in the terminal.

Run these commands from your terminal so you become comfortable with them outside the editor as well. They are the building blocks of every Go developer’s daily workflow.

Create Your First Workspace

Forget the old GOPATH/src structure. Modern Go uses modules, and a project can live anywhere on disk.

1. Create a new directory for your project:

mkdir hello-go
cd hello-go

2. Initialise a Go module:

go mod init hello-go

This creates a go.mod file that declares the module path and the Go version. It is the single source of truth for your project’s identity and dependencies.

3. Create a main.go file with a minimal program:

package main

import "fmt"

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

4. Run the program without building a separate binary:

go run .

You should see Hello, Go! printed to the terminal. This simple workspace is the template for every Go project you will build throughout this handbook.

Common Installation Problems

Problem	Likely cause and fix
go: command not found after installation	The Go binary is not in your PATH. Reopen your terminal or add the correct export line to your shell profile.
IDE cannot find the Go SDK	Ensure GOROOT is set correctly and the editor is configured to use the same Go installation as the terminal.
go mod init fails with permission error	You are probably inside a directory that requires elevated privileges. Move your project to your home directory.
Multiple Go versions installed	Check with which go (Linux/macOS) or where go (Windows). Remove old versions and keep only the latest stable release in your PATH.
go get or go mod tidy times out	Some corporate networks block the default Go proxy. Set GOPROXY=https://proxy.golang.org,direct or use GONOSUMDB and GONOSUMCHECK as appropriate.

If you hit a problem not listed here, the official Go troubleshooting guide and the output of go env are the best places to start.

Best Practices

• Use the latest stable release unless a project requirement dictates otherwise. Each release brings performance improvements and security fixes.
• Use Go Modules for every new project. They are the official standard and the only workflow that receives active development.
• Keep Go updated regularly. A simple re‑installation of the latest version takes minutes.
• Format all code with gofmt. Consistent formatting reduces noise in code reviews and eliminates style debates.
• Do not modify GOROOT manually. Treat the Go installation directory as read‑only. Any customisation should happen through environment variables or tool configuration.
• Organise projects with modules, not GOPATH. Place your projects where it makes sense for your work (e.g. ~/projects/hello-go), not inside a specific workspace directory.

Next Steps

Your Go environment is ready. Now it is time to write Go code with confidence.

• Your First Go Program – understand Go program structure, compilation, and execution in detail.
• Understanding Go Modules – learn dependency management and modern Go project organisation.
• Foundations – dive into variables, types, functions, and core language constructs.
• Concurrency – when you are ready, explore goroutines and channels—the heart of Go.

The installation is complete; the real work begins now.