google/pprof: reading profile.proto files and turning them into graphs

What google/pprof actually does, and what it refuses to do

The README states the scope in one line: pprof is a tool for visualization and analysis of profiling data. It reads a collection of profiling samples in profile.proto format and generates reports. That is the whole job. It does not attach to a process, schedule a sampling timer, or intercept allocations. Something else has to produce the samples first, and that producer is outside this repository.

The input is a protocol buffer described in proto/profile.proto. According to the README, it describes a set of callstacks and symbolization information, and a common usage is to represent sampled callstacks from statistical profiling. Because the format is the contract, pprof is not a Go-only tool in principle. Anything that can write profile.proto can be read by the same binary. The Go runtime is simply the most common source, which is why the project sits in the Go ecosystem and why the go.mod file targets Go 1.26.0.

The audience follows from that. If you have a profile file and no way to read it, pprof is the reader. If you have a running service and no profile, pprof is the wrong end of the pipeline.

From profile.pb.gz to an SVG: the report pipeline

Every pprof invocation takes profile inputs on the command line and an output-formatting option. The README describes profiles being read from a local file or over HTTP, and notes that multiple profiles of the same type can be aggregated or compared. That last point matters more than it looks: aggregation lets you merge several samples of the same kind, and comparison lets you diff two profiles of the same type, which is how you tell whether a change helped.

Symbolization is the second stage. If the samples contain machine addresses rather than resolved function names, the README says pprof can symbolize them through the native binutils tools addr2line and nm. This is why the main binary is passed as an argument in the examples: pprof needs the binary to map addresses back to functions. Without it, or without binutils, you get addresses instead of names.

Graphical output goes through the dot visualization package, which means Graphviz. The README lists Graphviz as optional, used to generate graphic visualizations. Optional is accurate: text reports work without it, and graphic visualizations do not. The repository layout reflects the same split, with a driver/ directory for the command, profile/ for the format handling, and internal/ for the rest.

Installing pprof and running a first text report

The README gives a single install command. It requires a Go development kit of a supported version, and Graphviz if you want graphic visualizations. The binary lands in $GOPATH/bin, which is $HOME/go/bin by default.

go install github.com/google/pprof@latest

After that, the first useful command is a text report sorted by hotness. The README's example takes an optional main binary for symbolization and a profile that is either a local compressed protobuf or a URL to an HTTP service that serves a profile.

pprof -top [main_binary] profile.pb.gz

The output is a ranked list of functions by cost. If you pass the main binary and the profile holds machine addresses, the names should be resolved; if symbolization fails, expect raw addresses and check that addr2line and nm are available.

For a visual report, the README shows the -web flag, which writes an SVG and opens it in a browser.

pprof -web [main_binary] profile.pb.gz

If you would rather work in a browser than in a terminal, the -http flag starts a web server. Host defaults to localhost and the port defaults to a random available one; -http=":" starts a server locally at a random port.

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

With no output formatting option at all, pprof drops into an interactive shell that reads the profile and accepts commands to refine and visualize it. Type help inside it for the available commands.

Where pprof stops being the right tool

The clearest limitation is structural: pprof does not collect data. If your program cannot emit profile.proto, you have nothing for it to read. The README does point at one bridge for this, the perf_to_profile program from the perf_data_converter package, which converts perf.data files generated by Linux perf into a form pprof can read. That conversion step is a real dependency, not a detail: a perf workflow without perf_to_profile has no path into pprof.

The second limitation is platform-specific and easy to miss. The README states that to view disassembly of profiles collected from Go programs compiled as Windows executables, the executable must be built with go build -buildmode=exe, and LLVM or GCC must be installed so that addr2line and nm are available. A default Windows build can therefore leave you without disassembly even though the profile itself loads.

The third is documentation depth. The README sends you to doc/README.md for more detailed end-user documentation, and the top-level file is short by design. Anything beyond the flags shown here, including the interactive command set, is documented elsewhere in the repository rather than in the README. Budget time to read doc/ before assuming a workflow is unsupported.

Finally, the README carries the line that this is not an official Google product. Treat support expectations accordingly.

pprof compared with Linux perf, and what the comparison really measures

The comparison that comes up most is pprof against perf. They sit at different layers. perf is a sampling profiler on Linux: it collects data from the kernel and writes perf.data. pprof is a reader and renderer for profile.proto. The two meet only through the converter named in the README, perf_to_profile from perf_data_converter, which turns perf.data into something pprof can open.

So the practical difference is not which one produces better reports. It is which format your data is already in. If you have perf.data and no converter, pprof has nothing to do. If you have profile.proto from a Go runtime or another producer, perf is not in the path at all.

A second difference is portability of the input. profile.proto is a protocol buffer with a published description in proto/profile.proto, and the README points at proto/README.md for the format details. A file format with a written spec is what allows readers and writers to be built independently, which is why the same binary can serve data from sources that have nothing to do with Go.

The trade-off is that pprof inherits every weakness of the format and of the symbolization step. Addresses without a matching binary stay unresolved. Missing binutils stay unresolved. pprof cannot fix either, because both are upstream of it.

Licence, maintenance and the cost of keeping up

The repository is licensed Apache-2.0, and the LICENSE file sits at the top level alongside AUTHORS and CONTRIBUTORS. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you are embedding the profile/ package rather than using the command. The README's disclaimer that this is not an official Google product is a support statement, not a licence term, and the two should not be confused.

On maintenance, the repository is not archived and the last push was on 2026-10-26. That is recent enough that the code is being touched, but the README does not describe a versioning or upgrade policy, and the repository has no published GitHub releases. The install path is go install github.com/google/pprof@latest, which tracks the latest module version rather than pinning one. If you need reproducibility, pin the module version in your own go.mod instead of relying on @latest.

The dependency surface is small. go.mod lists github.com/chzyer/readline for the interactive shell and github.com/ianlancetaylor/demangle for symbol demangling, with golang.org/x/sys as an indirect requirement. Upgrading pprof therefore mostly means tracking Go itself, since the module declares go 1.26.0. The upgrade cost is low; the operational cost is in the external tools, Graphviz for graphs and binutils for symbolization, which live outside the module and outside its versioning.

Editorial conclusion

Adopt google/pprof if you already have profile.proto data, or if you are profiling a Go program and want the standard report path. Do not adopt it expecting a profiler: pprof reads samples, it does not collect them, so you still need a runtime, a collector or a converter to produce the input. Before committing, confirm that your toolchain emits profile.proto, and check whether graph output matters to you, because -web and the visual reports depend on Graphviz being installed.

Frequently asked questions

Official sources

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