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.
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.
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.
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
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.proffollowed bygo tool pprof cpu.profis the lowest-effort path. - Servers import
net/http/pproffor its side effect and read profiles from/debug/pprof/; pointgo tool pprofat the URL. Never expose that handler publicly. - Flame graphs and the web UI from
-httpneed no extra software in recent versions. Older ones needed Graphviz for graph views. go tool coverneeds a profile file, not a package. Create it withgo test -coverprofile=cover.out ./....- Versions matter. Run the
go toolthat belongs to the toolchain that built the program, because profile and trace formats evolve. - Prefer
tooldirectives overtools.go. The old blank-import trick still works, but atoolline is clearer and does not drag the packages into your build.