heaptrack - Heap Memory Profiler for Linux Cheatsheet
heaptrack (by KDE) is a heap memory profiler for Linux. It traces all memory allocations and annotates each with a stack trace, so you can find leaks, allocation hotspots, excessive temporary allocations, and peak memory usage. It records a data file while your program runs, then analyzes it either with the heaptrack_gui (rich flame graphs and charts) or heaptrack_print (command-line). Overhead is low enough for realistic workloads.
Installation
| Platform | Command |
|---|
| Debian/Ubuntu | sudo apt install heaptrack heaptrack-gui |
| Fedora | sudo dnf install heaptrack heaptrack-gui |
| Arch Linux | sudo pacman -S heaptrack heaptrack-qt |
| From source | build from the KDE/heaptrack repo (CMake) |
| Verify | heaptrack --version |
Recording
| Command | Description |
|---|
heaptrack ./my-program args | Profile a command from the start |
heaptrack -p PID | Attach to a running process (GDB-based) |
heaptrack -o out.zst ./prog | Write to a specific output file |
| Output | Creates heaptrack.PROG.PID.zst in the current dir |
At exit, heaptrack prints a summary and the path to the recorded data file.
Analyzing (GUI)
heaptrack_gui heaptrack.my-program.12345.zst
| GUI view | Shows |
|---|
| Summary | Peak RSS, total allocations, leaked bytes |
| Flame graph | Allocations attributed to call stacks |
| Top-down / bottom-up | Call trees by allocation |
| Caller/callee | Navigate allocation relationships |
| Charts | Allocations/leaks/temporary over time |
Analyzing (CLI)
# Print the top allocation hotspots to the terminal
heaptrack_print heaptrack.my-program.12345.zst | less
| Metric | Meaning |
|---|
| peak | Maximum heap memory held at once |
| leaked | Memory allocated but never freed |
| allocations | Total number of allocations (churn) |
| temporary | Allocations freed almost immediately (waste) |
| Option | Description |
|---|
-a, --print-peak | Sort by peak memory consumers |
-l, --print-leaks | Show leaks |
-t, --print-temporary | Show temporary-allocation hotspots |
-d, --diff FILE | Diff two recordings |
Comparing Runs (Diff)
# See what changed between two builds/runs
heaptrack_print -d before.zst after.zst
What Each Metric Tells You
| Symptom | Look at |
|---|
| Process RSS keeps growing | leaked — allocations never freed |
| High allocator CPU cost | allocations / temporary — too much churn |
| OOM under load | peak — reduce max simultaneous memory |
| Startup memory spike | flame graph at the relevant time range |
Common Workflows
# Find a leak in a service
heaptrack ./myservice --run-workload
heaptrack_print -l heaptrack.myservice.*.zst | head -30
# Attribute peak memory during a heavy operation (GUI is easiest)
heaptrack ./batch-job
heaptrack_gui heaptrack.batch-job.*.zst # inspect the "peak" flame graph
# Reduce temporary-allocation churn in a hot loop
heaptrack_print -t heaptrack.*.zst | head
| Aspect | heaptrack | Valgrind (massif/memcheck) | Built-in allocators |
|---|
| Overhead | Low | High (memcheck very high) | Varies |
| Leak detection | Yes | Yes (memcheck) | Partial |
| Allocation churn | Yes (temporary) | massif focuses on peak | No |
| UI | Rich GUI + CLI | Text / massif-visualizer | None |
| Best for | Fast heap profiling on realistic runs | Deep correctness checks | Quick checks |
Resources
