pprof: Go Profiling Visualization and Analysis with a Web Interface and CLI

What pprof Does and Who Uses It

pprof is a tool for reading, analyzing, and visualizing profiling data. It reads samples collected in the profile.proto format, a protocol buffer that describes a set of callstacks and symbolization information. The most common use case is analyzing statistical CPU or memory profiles collected from a running Go program.

The tool produces multiple output formats: sorted text tables, interactive web interfaces, SVG and PDF call graphs, and raw text for scripting. Each output format answers a different question. The -top text report identifies the hottest functions by time. The -web graph shows the full call tree with edges weighted by sample count. The interactive web interface, accessible through any browser, lets developers navigate the same data with filtering and comparison controls.

Go developers are the primary audience. The tool ships as part of the Go profiling ecosystem and integrates directly with the net/http/pprof package in the standard library, which exposes live profiling endpoints. The profile.proto format is documented in the repository at proto/profile.proto, and any tool that writes to that format can be analyzed with pprof.

Installing pprof for Go Projects

The README gives a single install command:

go install github.com/google/pprof@latest

The binary installs to $GOPATH/bin, which defaults to $HOME/go/bin. If that directory is on your PATH, the pprof command is available immediately after.

Two prerequisites exist. The first is a Go development kit of a supported version. The README links to the Go release policy at golang.org/doc/devel/release.html for the current support window. The second is Graphviz, available at graphviz.org. Graphviz is optional but required for generating visual graph outputs like SVG and PDF. Text reports work without it.

The go.mod file shows two direct dependencies: github.com/chzyer/readline for the interactive shell, and github.com/ianlancetaylor/demangle for C++ symbol demangling. Both are lightweight. The module requires Go 1.25.0.

Text Reports, SVG Graphs, and the Interactive Shell

The README documents three main usage modes depending on what output is needed.

For a sorted text report of the hottest functions:

pprof -top [main_binary] profile.pb.gz

The main_binary argument is optional but enables symbolization: pprof uses addr2line and nm from binutils to map machine addresses in the profile back to function names and source locations. Without it, addresses appear as hex numbers.

For a call graph rendered as SVG and opened in a browser:

pprof -web [main_binary] profile.pb.gz

This requires Graphviz installed on the system. The graph shows each function as a node and each caller-callee relationship as an edge, with weight proportional to sample count.

For an interactive command shell where you can issue commands to refine and explore the profile:

pprof [main_binary] profile.pb.gz

Running pprof with no output flag drops into the interactive mode. The README notes that typing help in this shell lists all available commands and options.

The Web Interface: How to Start It and What It Offers

The web interface provides an interactive browser-based view of the profile. It starts with:

pprof -http=[host]:[port] [main_binary] profile.pb.gz

Host defaults to localhost. Port defaults to a random available port. The notation -http=: starts a server on localhost at a random port. The README states that the command should open the browser automatically; if it does not, the URL can be opened manually. Beyond what the text report shows, the web interface supports multiple visualizations of the same profile data: graph view, flame graph, top function table, and source annotation. Users can filter by function name regex, adjust the sample weight metric, and compare two profiles by specifying a base profile and a difference profile on the command line. The profile data can be read from a URL as well as a local file. If a Go application is running with net/http/pprof registered, pass the HTTP endpoint URL as the profile argument in place of a local .pb.gz file. The README notes that profiles can be read over HTTP using the URL to the service that serves a profile. Multiple profiles of the same type can be aggregated or compared by providing several file arguments on the command line.

Linux perf Integration and Windows Disassembly Requirements

pprof can read perf.data files generated by Linux perf, the kernel-level sampling tool. This requires the perf_to_profile program from the google/perf_data_converter package, which converts perf's format into profile.proto. The README documents this path at github.com/google/perf_data_converter.

This integration is useful for profiling Go programs alongside kernel activity, or for profiling C extensions and CGo calls where Go's own profiling does not reach.

On Windows, viewing disassembly of profiles collected from Go programs requires two conditions: the binary must be compiled with go build -buildmode=exe, and LLVM or GCC must be installed so that addr2line and nm are available. The standard Windows Go toolchain does not include those utilities by default, so LLVM (via winget, Chocolatey, or a manual install) is the practical path.

The -buildmode=exe constraint exists because Go on Windows can also produce DLLs and other binary formats that do not have the same debug layout that pprof expects for address symbolization.

The profile.proto Format and Multi-Profile Operations

The profile.proto file at proto/profile.proto is the full specification of pprof's data format. It defines a protocol buffer message that describes a collection of callstacks, each labeled with one or more numeric values (such as CPU time or bytes allocated), and a symbol table mapping address ranges to function names, source files, and line numbers.

Any profiler that writes to this format is immediately compatible with pprof's full feature set. Go's standard library net/http/pprof and runtime/pprof both produce this format. The README notes that profiles can be read from a local file or over HTTP.

Multiple profiles of the same type can be combined. Passing two profile files to pprof aggregates them into a single view. Passing a --base flag designates one profile as a baseline and shows the difference, which is the standard approach for before-and-after performance analysis: collect a profile before a change, collect one after, and compare the delta rather than reading absolute numbers.

Limitations and Comparison with Linux perf

pprof works on profile.proto data. If the profiler producing the data does not write to that format, the data cannot be read directly. The Linux perf conversion path requires the separate perf_data_converter tool, adding a step. For languages other than Go, custom instrumentation or a format adapter is needed.

Graphviz is required for graphical outputs. On minimal systems, CI environments, or Docker containers that do not have Graphviz installed, the -web, -svg, and -pdf outputs fail with a missing binary error. Text outputs work without it, but the visual representation is often the most useful for understanding a call graph.

Linux perf is the natural comparison. perf is a Linux-native sampling profiler that captures hardware performance counters, CPU cycles, cache misses, and context switches alongside callstack data. pprof does not read hardware counters; it works with statistical software samples. perf's data is harder to read without tooling but richer in low-level detail. For Go programs, pprof is the native choice because the runtime produces profile.proto data directly. For performance work that crosses into the kernel or native code, perf with a perf_data_converter step gives more complete information.

The repository is maintained by Google but carries the explicit disclaimer: this is not an official Google product. The last push was on 2026-09-26, and the Apache-2.0 license applies.

Editorial conclusion

pprof is the standard profiling tool in the Go ecosystem, and the go install path makes it trivial to add to any existing toolchain. The profile.proto format and the HTTP server mode mean it works with any Go application that exposes a pprof-compatible endpoint, without source changes. The main constraint is graphical output: generating SVG and PDF call graphs requires Graphviz to be installed separately. For Windows users who need disassembly, the binary must be built with go build -buildmode=exe, and LLVM or GCC must be present for addr2line. Teams working with Linux perf data need the separate perf_data_converter package from google/perf_data_converter. The tool is not an official Google product, as the README states explicitly.

Frequently asked questions

Official sources

1. google/pprof on GitHub
2. Issues
3. License: Apache-2.0
4. README