Go Installation and Setup Guide: Windows, Mac & Linux

Go Installation and Setup Guide: Windows, Mac & Linux

How to Install Go: Quick Answer

Download the Go installer for your OS from go.dev/dl, run the installer, and verify with go version in a new terminal. Go automatically adds itself to your system PATH. Then run go mod init <module-name> in your project directory to create a go.mod file — Go's equivalent of package.json.

Go Installation and Setup Guide

Before you can build high-performance network services or incredibly scalable cloud infrastructure with Go, you must install the language toolchain on your machine. Go is inherently designed for simplicity, and its installation reflects this philosophy.

This guide will walk you through installing the Go compiler on standard operating systems and setting up your first workspace configuration.

Downloading the Go Compiler

The official source for the Go compiler is the golang website.

When you navigate to the downloads page, select the appropriate installer for your operating system. For Windows and macOS, the process is as simple as downloading an executable installer and running it.

Verifying the Installation

Once the installation completes, open a brand new terminal window. This is critical, as your terminal needs to reload its environment variables to recognize the new executable.

Run the following command to verify everything is working correctly:

If the installation was successful, the terminal will output the installed version of Go alongside your system architecture, such as go version go1.22.1 windows/amd64.

Understanding the Go Workspace

Historically, Go required a very specific directory structure called the GOPATH to manage source code and dependencies. All your projects had to live inside this monolithic workspace folder.

This is no longer the case. Modern Go uses Go Modules to handle dependencies, allowing you to create your project directory anywhere on your entire file system.

To start a new project, create a new directory and navigate into it using your terminal:

Next, initialize the directory as a Go module. The convention is to use your repository URL (such as a GitHub link) as the module name to ensure global uniqueness, but for local testing, a simple name works perfectly.

This command creates a go.mod file, which is analogous to a package.json in the Node.js ecosystem. It specifies the Go version your project requires and will track any external packages you install.

Setting Up Your Code Editor

While you can technically write Go using any text editor, we strongly recommend using Visual Studio Code. The integration provided by the official Go extension creates a flawless developer experience out of the box.

Follow these steps to configure your editor:

1. Open Visual Studio Code.
2. Navigate to the Extensions panel (Ctrl+Shift+X or Cmd+Shift+X).
3. Search for "Go" and install the official extension published by the Go Team at Google.
4. Open your newly created my-first-go-server folder in VS Code.

When you create your first .go file, VS Code will likely prompt you with a notification asking to install required analysis tools like gopls (the Go language server), dlv (the debugger), and staticcheck (the linter). Click Install All to automatically download these powerful development tools directly into your system.

Essential Go CLI Commands

Once installed, the go command is your primary interface to the Go toolchain. Here are the commands you will use every day:

The go mod tidy command is particularly important to run before committing code — it ensures your go.mod and go.sum files are clean and accurate.

Understanding go.mod and go.sum

When you run go mod init, Go creates two important files:

go.mod

This file declares your module name, the Go version you are targeting, and your direct dependencies:

go.sum

This file contains the cryptographic checksums of every dependency and its transitive dependencies. It ensures that go get always downloads exactly the same code, preventing supply chain attacks where an attacker modifies a package after you added it.

Never manually edit go.sum. Let the Go toolchain manage it automatically.

Configuring VS Code for Go Development

After installing the Go extension in VS Code, configure a few settings in your .vscode/settings.json for the best experience:

These settings ensure:

• gopls (the official Go language server) provides autocomplete, type inference, and refactoring.
• Files are automatically formatted with gofmt on every save.
• Tests run with the race detector enabled by default.

Using GVM or asdf for Multiple Go Versions

If you work on multiple projects requiring different Go versions, a version manager is helpful. GVM (Go Version Manager) or asdf with the Go plugin let you switch versions per project:

For most developers, a single Go version is sufficient — Go has excellent backward compatibility.

Further Reading

• Official Go installation guide — go.dev

For the next step after installation, see Go Hello World basics where you write and run your first program. To understand what Go is and why it matters, see what is Go programming language. For the full course progression, start from the beginning of our Go module system tutorial.

Wrapping Up

Your local machine is now fully equipped to write, analyze, format, and compile Go code.

You have installed the toolchain, verified the compiler, initialized a modern module-based project directory, and configured a professional development environment. In the next tutorial, we will write your very first program and break down exactly how the execution flow works.

Common Setup Mistakes

1. Not removing the old Go version before installing a new one On Linux and macOS, previous Go installations live at /usr/local/go. Installing a new version without deleting the old directory first causes version conflicts. Always run rm -rf /usr/local/go before extracting the new archive.

2. GOPATH confusion Since Go 1.11, modules replace the old GOPATH-based workflow. You no longer need to put all projects inside $GOPATH/src. Create your project anywhere and run go mod init. The Go modules guide covers the transition in detail.

3. go not found after installation This almost always means the Go binary directory (/usr/local/go/bin on Linux/macOS, or the install path on Windows) is not in your PATH. Add export PATH=$PATH:/usr/local/go/bin to your .bashrc or .zshrc and reload the shell.

4. Using system package managers for Go apt install golang and brew install go often install outdated versions. Download directly from go.dev/dl to get the latest stable release.

5. Skipping go version verification After installation, always run go version to confirm the correct version is active. If you see an old version, a stale PATH entry is pointing at the previous installation.

Frequently Asked Questions

Which Go version should I install? Always install the latest stable release from go.dev/dl. Go maintains strong backward compatibility — code written for Go 1.18 still compiles under Go 1.22+. The release notes for each version are published at go.dev/doc/devel/release.

Do I need an IDE to write Go? No. Go can be written in any text editor. However, VS Code with the official Go extension (which bundles gopls, the Go language server) provides autocompletion, inline documentation, and automatic formatting — making it the most popular choice for Go development.

What is GOROOT vs GOPATH? GOROOT is where the Go toolchain itself is installed (usually /usr/local/go). GOPATH is the workspace directory for downloaded dependencies and cached builds — defaults to ~/go. In modern module-based Go, you rarely need to set either manually.