Go Handbook

Go (often called Golang, after its old website golang.org) is a small, compiled, statically typed language designed at Google by Robert Griesemer, Rob Pike and Ken Thompson and released as open source in 2009. It was built to fix the problems of large teams writing server software: slow builds, tangled dependencies and code that every engineer formats differently. The answer was a deliberately small language — about 25 keywords — that compiles in seconds to a single native binary and has concurrency built into the language itself.

That design made Go the language of cloud infrastructure. Docker, Kubernetes, Terraform, Prometheus, etcd, Consul, Caddy and the Grafana backend are all written in Go. If a company runs containers, it runs Go code every day, whether its own engineers write Go or not.

Download the official installer from go.dev/dl, or use your system's package manager. This handbook targets Go 1.22 or newer and every example was run on the current release. A few newer helpers are marked with the version that added them where they appear (b.Loop needs Go 1.24, sync.WaitGroup.Go needs 1.25), so install the latest release and everything here works as shown.

# Homebrew
brew install go

# or download the .pkg installer from https://go.dev/dl and double-click it
go version

# winget (built into Windows 10 and 11)
winget install GoLang.Go

# or download the .msi installer from https://go.dev/dl
# open a NEW terminal so PATH is refreshed, then:
go version

# official tarball (replace the version with the latest from go.dev/dl)
curl -LO https://go.dev/dl/go1.23.4.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
source ~/.profile
go version

Distribution packages (apt install golang-go) often ship an older Go. The official tarball is the safe choice.

go version should print something like go version go1.23.4 darwin/arm64. If the shell says command not found, the Go bin directory is not on your PATH — open a new terminal first, then check your shell profile.

Every Go project lives in a module: a folder with a go.mod file that names the project and records its dependencies. Create one with go mod init and a module path — for a project you might publish, that is usually a repository path like github.com/you/hello; for practice, any name works.

mkdir hello && cd hello
go mod init example.com/hello
# go: creating new go.mod: module example.com/hello

# create main.go (below), then:
go run .
# Hello, Go!

package main

import "fmt"

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

Hello, Go!

go run compiles the program into a temporary binary, runs it, and throws the binary away. It is what you use while writing code. go run . runs the package in the current folder; go run main.go runs one file (fine for the single-file examples in this handbook).

package main

import (
	"fmt"
	"os"
)

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

# command-line-arguments
./main.go:5:2: "os" imported and not used

package main

import "fmt"

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

package main

import "fmt"

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

# command-line-arguments
./main.go:6:1: syntax error: unexpected semicolon or newline before {

package main

import "fmt"

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

A Go source file always has the same three parts, in this order: a package clause, the imports, and then the declarations (functions, types, variables, constants). An executable program must be in package main and must have a func main() with no parameters and no return value — that is where execution starts.

// Package main is the entry point of an executable program.
package main

import (
	"fmt"
	"strings"
)

// greeting is package-level: visible to every function in the package.
const greeting = "hello"

/*
   Block comments exist, but Go code
   almost always uses // line comments.
*/
func main() {
	loud := strings.ToUpper(greeting) // call an exported function
	fmt.Println(loud, "from", "main")
}

HELLO from main

go build compiles your module into a single executable file. By default a pure-Go program is statically linked: the binary contains your code, every package it imports and the Go runtime (garbage collector and goroutine scheduler). Copy that one file to a server with the same OS and CPU and it runs — no Go install, no virtual machine, no dependency folder.

go build            # produces ./hello (hello.exe on Windows)
./hello
# Hello, Go!

go build -o bin/api .   # choose the output path

# cross-compile from your laptop for a Linux server
GOOS=linux GOARCH=amd64 go build -o hello-linux .

# a smaller release binary: strip debug info
go build -ldflags="-s -w" -o hello .

Cross-compiling is two environment variables. No extra toolchain is needed for pure-Go code.

gofmt rewrites your source into the one official Go style: tabs for indentation, aligned comments, sorted imports, standard spacing. There are no options to argue about, so every Go codebase in the world looks the same — reading a stranger's code feels like reading your own. Run go fmt ./..., or let your editor do it on save. Code reviews in Go teams simply reject unformatted code.

gofmt -l .          # list files that are not formatted
gofmt -d main.go    # show the diff gofmt would apply
go fmt ./...        # rewrite files in place
go vet ./...        # find likely bugs

go vet goes further: it catches code that compiles but is almost certainly wrong, like a Printf verb that does not match its argument. The program below compiles and runs, but vet flags it.

package main

import "fmt"

func main() {
	name := "Gopher"
	age := 14
	fmt.Printf("%s is %d years old\n", name, age)
	// go vet would flag the next line: %d given a string
	fmt.Printf("%d\n", name)
}

Gopher is 14 years old
%!d(string=Gopher)

Go does not run inside a browser tab, so this handbook does not pretend to. Instead, every example block is a complete program plus the exact output it prints — and every one was compiled and run with the real Go toolchain before it was published. If the page says a program prints 42, the program printed 42.

1. 1
   Read the example

   Predict the output before you look at it. Guessing wrong is where the learning happens.

2. 2
   Copy it into your editor

   Save it as main.go in a module folder and run go run main.go. Every example is self-contained and uses only the standard library.

3. 3
   Do the "Your turn" task

   Each example has a small change to make. Change it, predict, run.

4. 4
   Read the error cards

   Every red card is a real compiler or runtime message from Go, with why it happens and the fix. You will see these same messages in your own terminal.

5. 5
   Use the floating board

   Terms, key ideas and your progress for the module are collected on the floating board as you read.

6. 6
   Take the exam

   After the modules, the 25-question Go certification exam gives you a certificate at 70% or more.

Module

A Go project: a folder tree with a go.mod file that names it and pins its dependencies. Created with go mod init.

Package

A folder of .go files that share one package name. The unit of compilation and of visibility.

package main

The special package that compiles to an executable; it must contain func main().

Exported name

A name starting with an upper-case letter, visible to other packages.

Static binary

An executable that contains everything it needs (your code, libraries, the Go runtime), so it runs without installing anything else.

gofmt

The official Go formatter. Its output is the one accepted Go style.

go vet

A tool that reports code that compiles but is likely wrong, such as mismatched Printf verbs.