Read Build IDs from perf.data with perf buildid-list

You will use perf buildid-list to see which executable files, shared objects and kernel components a perf.data capture refers to. That gives you the identity information needed to find matching symbol tables before opening the capture in another tool. The examples take about five minutes if you already have a capture, and require no elevated privileges for an ordinary file you can read.

Before you start

1. Install a perf package that matches the kernel and distribution you are using. This machine has the linux-tools-common manpage package at version 6.8.0-142.142, but its perf launcher reports that tools for the running kernel 6.8.0-139 are not installed. A working, matching binary is therefore a prerequisite here.
2. Choose a readable perf data file. Replace /path/to/perf.data below with its real path. Do not overwrite the capture while investigating it.

test -r /path/to/perf.data && echo "capture is readable"
command -v perf
perf --version

If the first test is silent, fix the path or permissions. If perf --version fails because the running kernel has no matching tools, install the distribution package for that kernel or run a matching binary supplied by your distribution. The command in this guide cannot interpret a capture until the perf installation itself is usable.

List the binaries in a capture

1. Run the command with the capture supplied through --input. The option has the short form -i.

perf buildid-list --input=/path/to/perf.data

The output is a list of build IDs and the files they identify. The exact rows depend on what was recorded, so do not copy a made-up output into a report. A normal result contains entries for the DSOs present in the data, such as a program or shared library, and may include kernel-related entries. These identifiers are more useful than a filename alone: a rebuilt binary can have the same path while containing different code.

For a capture called perf.data in the current directory, the option can be omitted:

perf buildid-list

The documented default input is perf.data, except when standard input is a FIFO. Being explicit with --input is less distracting in scripts and makes it harder to inspect the wrong file in a directory containing several captures.

Show only binaries that had hits

Large captures can mention DSOs that were mapped but did not contribute samples. Use --with-hits, or its short form -H, to reduce the list to DSOs with hits:

perf buildid-list --input=/path/to/perf.data --with-hits

This is a filtering choice, not a change to the capture. Start without the filter when you are establishing the complete set of build IDs. Use it when you are narrowing a performance question to code that actually received samples. If a library you expected is absent from the filtered result, repeat the command without --with-hits before concluding that the library was never present.

Inspect the running kernel

The command also has modes that do not read a perf.data file. Use --kernel, or -k, to show the build ID of the running kernel:

perf buildid-list --kernel

Use --kernel-maps, or -m, when you need the running kernel and its modules together with the start and end text addresses and paths:

perf buildid-list --kernel-maps

These modes describe the current running system, not necessarily the kernel that produced an older capture. That distinction is an easy source of false matches. For a historical investigation, treat the build IDs from the capture as authoritative for the recorded data and use the live kernel modes only when you are deliberately checking the current host.

Depending on the system's access controls, kernel inspection may need permissions that an ordinary user does not have. If the command reports a permissions error, first check whether the information is available under the account that owns the capture and the system you are examining. Use elevated privileges only according to your local policy; do not add sudo routinely to a command that only reads a user-owned file.

Read an ELF file directly

The --input option can also name an ELF file. This is useful for checking the build ID of one binary without creating a perf capture:

perf buildid-list --input=/usr/bin/ssh

Replace the example path with the executable or shared object you want to identify. The file must be readable. If the command rejects it, check that it is an ELF object and that the path is not a script, compressed file or unrelated text file. A successful result lets you compare that object's build ID with an entry from the capture.

Do not treat a matching pathname as proof that the files match. Package upgrades, local rebuilds and container images can all reuse a pathname. Compare the build ID, then obtain symbols from the package or build that produced that exact identifier. The command lists identity information; it does not fetch packages or install debug symbols.

Make diagnostics more detailed

Add --verbose, or -v, when the normal output does not give enough context for troubleshooting:

perf buildid-list --input=/path/to/perf.data --verbose

Use this as a diagnostic retry rather than assuming that verbose output changes what is recorded. It may expose useful details about how perf is interpreting the input, but the exact text is version-dependent.

Common failure traps

• Wrong file: the no-option form reads perf.data in the current directory. Print your working directory with pwd, or always use an absolute --input path when captures are stored elsewhere.
• Kernel and tool mismatch: a system can have the common documentation installed while lacking the binary package for its running kernel. Treat the warning from perf as an installation problem, not as evidence that the capture is corrupt.
• Missing symbols: a build ID identifies the required binary, but this command does not provide its symbol table. Keep the ID and path, then obtain matching debuginfo through your normal package or build process.
• Unexpectedly short output: --with-hits deliberately removes DSOs without hits. Re-run without that option to distinguish filtering from missing data.
• Ownership checks: the --force option disables ownership validation. That is a security-sensitive exception. Use it only when you understand why the normal validation rejects the file and have checked its provenance. It does not repair or alter the capture.

None of the examples in this guide modifies perf.data, the kernel, loaded modules or installed packages. If you accidentally point the command at the wrong file, stop and rerun it with the correct explicit path. There is no data-changing action here that needs an undo command.

Done means

• You can run perf buildid-list --input=/path/to/perf.data with a usable, matching perf installation.
• You have recorded the build IDs and paths returned for the capture you are analysing.
• You know whether --with-hits was used and have repeated the unfiltered command when completeness matters.
• You have not confused the current kernel's build ID with the kernel identity recorded in an older capture.
• You will obtain symbols for the exact build IDs before relying on perf report results.