Getting Started

Go is a compiled, statically typed, garbage-collected language. It was designed to make large software projects and their build systems less painful: fast builds, a small language that is quick to read, first-class support for concurrency on multicore machines, and tooling (formatting, documentation, testing, dependency management) that ships with the language and works the same way for everyone. The Go FAQ describes the motivation as frustration with the complexity of building big systems in the languages of 2007, together with the need for safe, simple concurrency and automatic memory management.

Go is a deliberately small language. If you know Rust, compare this page with Getting Started in the Rust Reference: both ship one tool that builds, tests, formats and manages dependencies, but Go trades Rust’s compile-time ownership checking for a garbage collector and a much shorter list of features. Readers coming from C will find the same "compile to a native binary" workflow as in Getting Started in the C Reference, with a module system instead of Makefiles and header files.

Download the archive or installer for your platform from the official download page. A Go installation is a single directory tree (GOROOT) containing the go command, the compiler, linker and other tools under pkg/tool, and the standard library sources. There is no separate runtime to install: compiled programs carry their own.

go is the single entry point for everything: building, running, testing, formatting, documentation, dependency management and diagnostics. go help prints the command list; these are the commands in go1.27.2:

go help <command> documents one command; go help also has topic pages such as buildconstraint, buildmode, cache, environment, modules, module-auth, packages and testflag.

Source: cmd/go

See Go IDEs & Tools for a list of IDEs and editors.

You can write Go in any text editor, but the experience is much better with the official language server, gopls, which the Go team maintains. It gives diagnostics as you type, completion, go-to-definition, find references, rename, code actions (including go fix modernizers) and organizing imports, in any editor that speaks the Language Server Protocol. Install it once; most editor plugins do this for you:

This command downloads from the network, so it is not run in the sandbox that produced the outputs on this page; gopls@v0.24.0 is the release current on 2026-10-18.

Two conventions are worth setting up on day one: format on save (the editor runs gofmt, or gopls does it for you, so formatting never shows up in code review) and organize imports on save (gopls adds and removes import lines). The debugger of choice is Delve (dlv), which understands goroutines and is what the editor integrations drive.

Source: Editor plugins and IDEs and gopls documentation

A Go program lives in a module: a directory tree with a go.mod file at its root that names the module and records the Go version and dependencies. The code inside is organized in packages, one per directory. A package named main that declares a function main builds into an executable.

go mod init takes the module path, which should be the place the module will be downloadable from (a repository URL without the scheme). The go line it writes is the toolchain’s own version: with go1.27.2 the file says go 1.27.2. The Go 1.26 release notes announced that go mod init would write the version of the previous release, so check what your toolchain writes. Either way, you set the minimum Go version explicitly with go mod edit -go=1.27 or, when the toolchain can be downloaded, go get go@1.27. The go.mod file for the rest of this page:

Now the program, in main.go:

Source: Tutorial: Get started with Go

Three commands turn it into something you can run:

(GOBIN is set explicitly in the sandbox that produced this output; by default go install writes to $GOPATH/bin.)

go run accepts several forms of the package argument:

Real programs are more than one file. The shelf module used throughout this section has this layout:

Conventions visible here: a package lives in one directory and its name is the last element of its import path; a cmd/ directory holds one subdirectory per executable; and an internal/ directory makes its packages importable only from within the parent of internal (enforced by the compiler). Exported names begin with a capital letter, and that is the entire visibility mechanism. The program in cmd/shelf/main.go uses the other two packages:

./... is a package pattern: the current directory and every directory below it that contains Go files. go build ./... compiles everything but writes no executables when several packages are named; go install ./cmd/shelf installs one command. gofmt -l . lists files whose formatting differs and, printing nothing here, confirms every file is formatted. The packages themselves are covered in Packages, Imports and Initialization.

Source: How to Write Go Code and Organizing a Go module

The official create a module tutorial builds a library in one module and uses it from another. Here is the same idea, condensed, with a welcome library for the shelf front desk. Two sibling directories, each its own module:

Source: Tutorial: Create a Go module

The caller lives in desk/, a second module that imports example.com/welcome:

Building straight away fails, because nothing tells the go command where example.com/welcome comes from. For a published module go get or go mod tidy would fetch it. For a module on your own disk, a replace directive points to the directory:

The second call deliberately passes an empty name: log.Fatal prints the error with the desk: ` prefix and exits with status 1, which `go run reports as exit status 1. The placeholder version v0.0.0-00010101000000-000000000000 is what the go command invents for a directory replacement.

Source: Tutorial: Create a Go module and Tutorial: Call your code from another module

A replace is part of go.mod, so it travels with the repository, which is rarely what you want for a local-only arrangement. The alternative is a workspace: a go.work file next to both modules that use`s them, with no changes to either `go.mod:

Workspaces, go.work and publishing a module with proper version tags are the subject of Workspaces, Versioning and Publishing.

Source: Tutorial: Getting started with multi-module workspaces

Go has one canonical layout, produced by the gofmt tool. It indents with tabs, aligns comments and struct fields, and leaves line breaks where you put them. Because there is exactly one result, formatting arguments do not happen. go fmt runs gofmt -l -w over a package; gofmt -d shows a diff instead of rewriting; gofmt -s also simplifies code.

Source: cmd/gofmt

(This sample is deliberately badly formatted; every other example in this section is gofmt-clean.)

Formatting never changes meaning, with one exception that comes from the language itself: semicolon insertion. The grammar uses semicolons, but the lexer inserts one automatically at the end of a line that ends in an identifier, a literal, one of break, continue, fallthrough, return, one of the operators ++ or --, or a closing ), ] or }. The practical consequence is that the opening brace must stay on the line of the statement it opens:

The line func main() ended in ), so a semicolon was inserted and the { on the next line no longer belongs to anything. The same rule is why a multi-line call or composite literal needs a trailing comma after its last element. The full lexical rules are in Program Structure and Lexical Elements.

Source: The Go Programming Language Specification: Semicolons and cmd/gofmt

go build hides a long pipeline behind one command. The figure shows the stages from source to executable and where the neighbouring tools (gofmt, go vet and the build cache) fit.

The compiler (go tool compile) works one package at a time, in dependency order. It parses source into a syntax tree (inserting semicolons as described above), type-checks it, optimizes it (inlining small functions, deciding which values may stay on the stack), turns it into an SSA form where most optimizations run, and emits machine code. The result for a package is an archive: object code plus the exported type information that importers need. The build cache stores each archive under a hash of everything that influenced it, so unchanged packages, including the standard library, are not recompiled. The linker (go tool link) then reads the archives of the program and all its dependencies together with the runtime package (scheduler, garbage collector, memory allocator), discards unreachable functions and writes one executable. Nothing else needs to be present on the machine that runs it.

You can watch the tool invocations. -n prints the commands without running them (-x prints and runs them); with -a to ignore the cache and a filter to keep only the compile of the program and the link, with the path to the toolchain shortened:

Two things stand out. The compiler is told -lang=go1.27, which comes straight from the go line of go.mod: that line chooses the language version a package is compiled with (see the toolchain page). And the link step takes only the archive of the program plus an import configuration naming every dependency’s archive.

Source: cmd/compile, cmd/link and cmd/go: Build and test caching

The Go Playground at https://go.dev/play/ compiles and runs a single program on Google’s servers and gives you a link to share it. It is perfect for small experiments, bug reports and snippets in a chat. It runs in a sandbox: limited CPU and memory, no real network, a fake file system, and a fake clock that starts on 2009-11-10 and advances only when programs sleep, so that goroutine demos behave sensibly without waiting. Programs that need the network, real time or several files need a real toolchain.

A Tour of Go at https://go.dev/tour/ is an interactive introduction in four parts: basic syntax and data structures, methods and interfaces, generics, and concurrency, with exercises. It runs in the browser on the Playground, or locally with go install golang.org/x/website/tour@latest (network access required; not run here). Read it together with this section.

Source: The Go Blog: Inside the Go Playground and A Tour of Go

Compiler errors have the form file:line:column: message and come in the order of the lines they refer to. The compiler reports at most ten errors and then prints too many errors; -gcflags=-e removes that limit. One broken file shows several of the most common ones at once (the program is deliberately wrong and does not compile):

The ten-error limit in action, with twelve unused variables in one function:

Source: The Go Programming Language Specification: Declarations and scope and cmd/compile

Both books used for this section were written before modules, the module proxy, the toolchain line and go fix modernizers existed in their current form; the facts they teach about the language are largely still right, but the set-up chapters are not.

The books also show tool output captured with Go 1.6 to 1.16; compiler messages have been reworded since (for example declared and not used: count, which now names the variable), so do not match them literally.