Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go tool command

Reference for the go tool command: list and run the built-in tools such as pprof, trace and cover, plus tools tracked with the tool directive in go.mod.

go tool runs one of the lower-level programs that ship with the Go distribution. Most of them are driven for you by other commands (go build calls compile and link, go vet calls vet), but a few are meant to be used by hand: pprof to read performance profiles, trace to inspect execution traces, and cover to turn a coverage profile into a report.

Since Go 1.24 the same command also runs module tools: programs from other modules that your go.mod lists with a tool directive. That replaces the old habit of a tools.go file full of blank imports.

Terminal
go tool                         # list the tools
go tool cover -html=cover.out   # open a coverage report in the browser
go tool pprof -http=:8080 cpu.prof
go tool -n compile              # print the path instead of running it

Try it

The profiling and tracing tools read files that your program writes with the standard library. These programs produce such data in memory, so you can see what the tools are given.

Go Writing a goroutine profile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Recording an execution trace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Terminal
go tool [-n] command [args...]
Part Description
command The tool name, such as pprof, or the last path element of a tool listed in go.mod.
-n Print the command that would run, but do not run it.
args... Passed to the tool unchanged.

With no arguments go tool prints the available tools. The set depends on the Go version and platform; it includes addr2line, asm, buildid, cgo, compile, covdata, cover, doc, link, nm, objdump, pack, pprof, test2json, trace and vet.

The tools you will use most:

Tool What it does
pprof Reads CPU, heap, goroutine, block and mutex profiles. -top prints a table, -list name shows source lines, -http=:port starts a web UI with flame graphs.
trace Opens an execution trace (written by runtime/trace or go test -trace) in the browser: goroutine timelines, GC events, scheduler latency.
cover -func=file prints per-function percentages, -html=file renders annotated source. Input comes from go test -coverprofile.
objdump, nm Disassemble a binary or list its symbols.
compile, link, asm The compiler, linker and assembler. Called by go build; rarely run directly.

Module tools (Go 1.24+). go get -tool example.com/cmd/stringer@latest records a tool line in go.mod, and go tool stringer then runs that exact version. go install tool installs all of them, and the pattern tool in go build tool or go list tool means the same set.

Errors and edge cases: an unknown name fails with go: no such tool "name". The module-tool lookup does not need the program to be installed anywhere; it is built on demand and cached.

Usage notes

  • Profile in tests first. go test -bench . -cpuprofile cpu.prof followed by go tool pprof cpu.prof is the lowest-effort path.
  • Servers import net/http/pprof for its side effect and read profiles from /debug/pprof/; point go tool pprof at the URL. Never expose that handler publicly.
  • Flame graphs and the web UI from -http need no extra software in recent versions. Older ones needed Graphviz for graph views.
  • go tool cover needs a profile file, not a package. Create it with go test -coverprofile=cover.out ./....
  • Versions matter. Run the go tool that belongs to the toolchain that built the program, because profile and trace formats evolve.
  • Prefer tool directives over tools.go. The old blank-import trick still works, but a tool line is clearer and does not drag the packages into your build.