The go tool

Go ships as a single go binary that builds, tests, formats, generates, documents, and profiles. Every subcommand, with its flags and a worked example.

One binary does the whole job: compiling, running, testing, formatting, dependency management, documentation, and profiling. There is no separate build tool, formatter, or package manager to install.

Click any command for its flags and a worked example, or filter to jump straight to one.

go 32 commands and the flags each one takes

Build and run

go run <pkg|file...>
$ go run .
Compiles and runs a program, leaving no binary behind.
Builds into a temporary directory and executes the result. Arguments after the package go to the program, not to the go tool: go run . -port 9000 passes -port 9000 through.
Flags
-race Enable the data race detector.
-tags Comma-separated build tags to satisfy.
go build [pkg...]
$ go build -o bin/app .
Compiles packages into a binary without running it.
Writes the binary into the current directory, named after the module or directory, unless -o says otherwise. Building a non-main package compiles it and discards the result, which makes go build ./... a fast whole-repo compile check.
Flags
-o Write the binary to this path.
-race Enable the data race detector.
-ldflags Pass flags to the linker, commonly -ldflags="-X main.version=1.2.3".
-trimpath Strip local filesystem paths out of the binary.
go install <pkg>[@version]
$ go install golang.org/x/tools/cmd/stringer@latest
Builds a command and puts the binary in GOBIN.
With an @version suffix it installs without touching the current module's go.mod, which is how you install a tool. Without one it installs from the current module. The binary lands in GOBIN, or GOPATH/bin when that is unset.
go clean
$ go clean -cache -testcache
Removes object files and cached build artifacts.
Flags
-cache Empty the whole build cache.
-testcache Expire cached test results.
-modcache Delete the downloaded module cache.

Test and check

go test [pkg...]
$ go test ./...
Builds and runs the tests in each named package.
Results are cached. A second run of an unchanged package prints (cached) instead of running anything, and -count=1 is the documented way to force a real run.
Flags
-v Print each test name and its log output.
-run Run only tests whose name matches this regular expression.
-cover Report statement coverage.
-race Enable the data race detector.
-bench Run benchmarks matching this regular expression.
-count=1 Bypass the test cache.
terminal
```
ok      example.com/hello       0.002s
ok      example.com/hello/store (cached)
```
go vet [pkg...]
$ go vet ./...
Reports suspicious constructions the compiler accepts.
Catches mistakes that compile: a Printf verb that does not match its argument, a struct tag that will not parse, a lock copied by value, an unreachable return. It runs automatically as part of go test.
terminal
```
./main.go:8:2: fmt.Printf format %s has arg count of wrong type int
```
go fix [pkg...]
$ go fix ./...
Rewrites code that uses old APIs to the current ones.
Applies the same rewrites go tool fix knows about. It edits files in place, so commit first.
go bug
$ go bug
Opens a browser to file a Go issue, with your environment filled in.

Format and generate

go fmt [pkg...]
$ go fmt ./...
Formats the source in each named package and prints what it changed.
A wrapper that runs gofmt -l -w over the package's files. Go has one canonical layout and no configuration for it: indentation is tabs, alignment is spaces, and neither is a preference. Editors normally run this on save, so a repository where go fmt ./... prints nothing is the normal state.

Use gofmt directly when you want the options the wrapper does not expose, such as -d to see a diff without writing.
terminal
```
main.go
internal/store/store.go
```
gofmt -l -d <path>
$ gofmt -l -d .
Lists unformatted files and prints the diff, changing nothing.
The form to use in CI. -l lists the files that need formatting, -d prints the diff, and neither writes. A non-empty output means the build should fail.
Flags
-l List files whose formatting differs.
-w Write the result back to the file.
-d Print a diff instead of the formatted file.
-s Simplify code where it can.
go generate [pkg...]
$ go generate ./...
Runs the commands named in //go:generate comments.
Scans for lines of the form //go:generate command args and runs each one in the directory of the file that holds it. Nothing runs automatically: go build and go test never trigger it, so generated files are committed and regenerated deliberately.

The comment has no space after //. // go:generate is an ordinary comment and is silently ignored.
Flags
-n Print the commands without running them.
-x Print each command as it runs.
-run Only run commands matching this regular expression.
terminal
```
// status.go
//go:generate stringer -type=Status

type Status int

$ go generate ./...
$ ls
status.go  status_string.go
```

Documentation and environment

go doc [pkg][.<name>]
$ go doc bufio.Scanner
Prints the documentation for a package, type, function, or method.
The fastest way to answer "what does this return" without leaving the terminal. It reads the source on your machine, so the version it describes is the version you are compiling against.

The argument narrows as you add to it: a package name gives the summary, a dotted name gives one symbol, and a second dot reaches a method on a type.
Flags
-all Print all documentation for the package, not just the summary.
-src Show the source code of the symbol.
-u Include unexported identifiers.
-c Match the symbol name case-sensitively.
terminal
```
$ go doc bufio                # the package summary
$ go doc bufio.Scanner        # one type
$ go doc bufio.Scanner.Scan   # one method on it
$ go doc -src bufio.NewScanner
$ go doc net/http.Client      # full import path when ambiguous

$ go doc bufio.Scanner.Scan
package bufio // import "bufio"

func (s *Scanner) Scan() bool
    Scan advances the Scanner to the next token, which will then be
    available through the Scanner.Bytes or Scanner.Text method. It
    returns false when there are no more tokens, either by reaching the
    end of the input or an error.
```
go version [-m <binary>]
$ go version -m ./app
Prints the Go version, or the versions built into a binary.
-m reads the module information embedded in a compiled binary, including every dependency version. It works on any Go binary, which makes it the quickest way to audit something you did not build.
terminal
```
go version go1.26.1 linux/amd64
```
go env [-w] [var...]
$ go env GOMODCACHE
Prints the Go environment, or sets a value with -w.
Naming variables prints only those, one per line, which is what makes it usable in a script. -w writes a persistent default into the user's env file, and -u removes it again.
Flags
-w Set a variable persistently.
-u Unset a variable previously set with -w.
-json Print the whole environment as JSON.
terminal
```
$ go env GOMODCACHE
/home/you/go/pkg/mod
```
go list [pkg...]
$ go list -m -u all
Reports information about packages and modules.
The scriptable view of everything the tool knows. -f takes a text/template, so you can print any field of the package or module struct.
Flags
-m List modules instead of packages.
-u Add available upgrades to the module listing.
-json Print the full record as JSON.
-f Format each record with a text/template.
terminal
```
$ go list -f '{{.ImportPath}} {{.GoFiles}}' ./...
example.com/hello [main.go]
```

Modules and dependencies

go mod init <module-path>
$ go mod init example.com/hello
Creates a go.mod file in the current directory.
The module path is the string other code will import, so it is normally the repository URL. It is not a filesystem path and does not have to resolve while you are developing.
go mod tidy
$ go mod tidy
Adds missing module requirements and drops unused ones.
Reads every import in the module and reconciles go.mod and go.sum against them. It is the command to run after adding or deleting an import, and the one CI should check leaves no diff.
terminal
```
go: finding module for package github.com/gofiber/fiber/v3
go: found github.com/gofiber/fiber/v3 in github.com/gofiber/fiber/v3 v3.4.0
```
go get <pkg>[@version]
$ go get github.com/jackc/pgx/v5@v5.10.0
Adds, upgrades, or removes a dependency in go.mod.
Since Go 1.17 this only edits dependencies; installing a tool binary is go install. The version suffix takes a tag, a branch, a commit, @latest, or @none to remove the dependency.
Flags
-u Upgrade to the latest minor or patch release.
-u=patch Upgrade to the latest patch release only.
go mod download [modules]
$ go mod download
Downloads modules into the local module cache.
Useful as its own Docker layer: copy go.mod and go.sum, download, then copy the source, so a code change does not re-fetch every dependency.
go mod verify
$ go mod verify
Checks that cached dependencies match the hashes in go.sum.
terminal
```
all modules verified
```
go mod why <pkg>
$ go mod why golang.org/x/text
Explains why a package or module is needed.
Prints the shortest import chain from a package in the main module to the one you named, which is how you find out who pulled in a dependency you did not add.
go mod graph
$ go mod graph
Prints the module dependency graph, one edge per line.
go mod edit <flags>
$ go mod edit -replace=old.dev/x=../x
Edits go.mod from a script, without a text editor.
Flags
-require Add or update a requirement.
-replace Point a module path at another module or a local directory.
-droprequire Remove a requirement.
-go Set the go directive's language version.
go mod vendor
$ go mod vendor
Copies every dependency into a vendor directory.
Once vendor/ exists the tool builds from it by default, ignoring the module cache. -mod=mod overrides that for one command.

Workspaces

go work init [dirs...]
$ go work init ./api ./worker
Creates a go.work file covering several modules at once.
A workspace lets modules in different directories see each other's local changes with no replace directive in any go.mod. go.work is a local development file and is normally left out of version control.
go work use [dirs...]
$ go work use ./billing
Adds a module directory to the workspace.
go work sync
$ go work sync
Pushes the workspace's resolved versions back into each module's go.mod.

Tools and diagnostics

go tool [name] [args]
$ go tool pprof cpu.out
Runs one of the tools shipped with the toolchain.
With no arguments it lists what is available. Since Go 1.24 it also runs tools declared in the module's go.mod with a tool directive, which is how a project pins its own linters and generators.
terminal
```
$ go tool
addr2line
asm
buildid
cgo
compile
covdata
cover
dist
distpack
doc
fix
link
nm
objdump
pack
pprof
test2json
trace
vet
```
go tool pprof <profile>
$ go tool pprof -http=:8081 cpu.out
Opens a CPU, memory, or block profile for analysis.
-http serves an interactive flame graph in the browser rather than dropping into the terminal prompt. Produce the profile with go test -cpuprofile cpu.out or the net/http/pprof handlers.
go tool trace <trace file>
$ go tool trace trace.out
Opens an execution trace, showing goroutines and the scheduler.
go tool cover <flags>
$ go tool cover -html=cover.out
Renders a coverage profile as annotated source.
Pairs with go test -coverprofile=cover.out. The HTML view colors every statement by whether a test reached it.
go telemetry <on|off|local>
$ go telemetry off
Controls whether the toolchain uploads usage telemetry.
Off by default: nothing is uploaded unless you opt in. local keeps counters on disk without sending them, and off stops collection entirely.

Set up Environment Installing Go, PATH, and your first module.Reference The standard library packages go doc will print for you.flag Giving your own program the kind of flags listed here.Bound goroutines with a worker pool Code worth pointing go test -race at.

Next Topic Set up Environment

The go tool

Related