Cargo Flamegraph on Linux and Macos Setup Steps Step by Step
Generate a flamegraph from a Rust program on Linux or macOS: install, enable symbols, allow perf access, record and read the SVG, and fix the empty-graph problems.

A flamegraph shows in one picture where a program spends its time. Generating one for a Rust binary is five minutes of setup the first time and one command afterward. Most failures are the same three: no symbols, no permission to sample, or a program that exits too quickly. This post walks through the setup for Linux and macOS. It supports the profiling guide.
flamegraph 0.6, Rust 1.90.
Install
cargo install flamegraphOn Linux install perf first: sudo apt install linux-perf or the package for your kernel (linux-tools-generic on Ubuntu). macOS needs the Xcode command line tools for dtrace.
Keep symbols in release
[profile.release]
debug = "line-tables-only"This leaves optimization alone and records function names and line numbers.
Allow sampling on Linux
sudo sysctl kernel.perf_event_paranoid=1
sudo sysctl kernel.kptr_restrict=0These settings let a normal user sample. They reset on reboot unless written to /etc/sysctl.d/. Without them perf fails with Access to performance monitoring and observability operations is limited. In a container, add --cap-add SYS_ADMIN or run perf on the host; profiling inside Docker needs the capability and a matching perf binary.
Record
A program worth profiling:
use std::collections::HashMap;
fn main() {
let mut counts: HashMap<String, usize> = HashMap::new();
for i in 0..5_000_000u32 {
let key = format!("key{}", i % 1000);
*counts.entry(key).or_insert(0) += 1;
}
println!("{}", counts.len());
}cargo flamegraph --bin demoThe tool builds in release, runs under the profiler and writes flamegraph.svg. On macOS add sudo, or cargo flamegraph --root. Pass arguments to your program after --: cargo flamegraph --bin demo -- data.csv.
Read it
For this example, the widest frames will be alloc::fmt::format and the malloc family under it, then the HashMap entry call. That tells you the key construction is the cost, and the fix is to avoid building a String for each lookup: look up with a &str, or intern keys. The reading rules are in the profiling guide.
Click a box to zoom to it, use the search box to highlight a name, and read widths as share of time. Colors are only for contrast.
Troubleshooting
| Symptom | Fix |
|---|---|
| Frames are hex addresses | add debug = "line-tables-only" |
perf permission error | perf_event_paranoid as above |
Graph has only _start and main | the program is too short; loop the work |
| Inlined functions missing | expected in release; they are attributed to their caller |
| Async code shows mostly runtime frames | enable tokio task names or use tokio-console |
Alternatives
samply record ./target/release/demo opens the Firefox Profiler with a timeline and works on macOS without sudo. perf record plus perf report gives a text view. cargo-instruments integrates with Xcode on macOS. The tool is documented in the flamegraph-rs repository.


