Check the Installed perf Version Before Profiling

You will check which perf command is being selected, display its version, and inspect the libraries compiled into the binary. You will also be able to tell the difference between a normal version result and the Debian or Ubuntu wrapper finding no kernel-specific perf binary. Allow about ten minutes. You need a shell and the linux-tools-common package; no command in this guide needs elevated privileges.

The examples use the installed perf entry point and its perf version subcommand. On this machine, linux-tools-common is version 6.8.0-142.142, while the running kernel is 6.8.0-139-generic. Those values are host-specific, so record yours rather than copying them into a report.

1. Confirm the command you are about to run

Start with ordinary, read-only checks. They show the command path, the package providing the entry point, and the running kernel:

$ command -v perf
/usr/bin/perf
$ dpkg-query -W -f='${Package} ${Version}\n' linux-tools-common
linux-tools-common 6.8.0-142.142
$ uname -r
6.8.0-139-generic

Your package version and kernel release will probably differ. The important detail is that /usr/bin/perf can be a selector rather than the profiling binary itself. It looks for a perf binary matching the running kernel, then prints a warning if that binary is unavailable.

2. Display the perf version

Run the subcommand with no options:

$ perf version
perf version 6.8.0

The exact version line depends on the binary supplied for your kernel. The command writes the version to standard output and returns success when it can run that binary. Do not parse the example's number as a universal answer; use the output from your own host.

The command is perf version, not a separate invocation of a program named perf-version. The installed manual page is named perf-version(1) because it documents this subcommand.

3. Handle a missing kernel-specific binary

On this machine the same command cannot reach a versioned perf binary. Its output is:

$ perf version
WARNING: perf not found for kernel 6.8.0-139

  You may need to install the following packages for this specific kernel:
    linux-tools-6.8.0-139-generic
    linux-cloud-tools-6.8.0-139-generic

  You may also want to install one of the following packages to keep up to date:
    linux-tools-generic
    linux-cloud-tools-generic

The warning is not a perf version. It means that the /usr/bin/perf wrapper from linux-tools-common could not find the kernel-matched binary. Capture the exit status immediately if a script needs to distinguish this case:

$ perf version
$ status=$?
$ printf 'perf version exit status: %s\n' "$status"
perf version exit status: 2

The status and warning text shown above are the result on this host. On another distribution or release, the wrapper and its diagnostics may differ. If your command reports a missing binary, use the package names it prints as leads for your normal package-management process. Installing a package changes system state and may require sudo; do that only after checking the kernel release and your repository policy.

Do not treat a missing binary as evidence that the kernel has no performance events, and do not work around it by copying an unrelated perf binary into a system directory. Match the tool to the running kernel through the distribution packages.

4. Inspect compiled-in library support

Once perf version can run, add --build-options:

$ perf version --build-options
perf version 6.8.0
                 dwarf: [ on  ]
    syscall_table: [ on  ]
         libunwind: [ on  ]
             ...

This option prints the status of libraries compiled into the perf binary. The list and formatting are build-specific, so the abbreviated output above is only a shape guide. Read the complete output from your host when deciding whether a feature is available. A library shown as disabled is a build characteristic, not something this command enables.

On the current host, perf version --build-options fails for the same reason as the plain version command: the wrapper cannot find the kernel-specific binary. Fix the package mismatch first, then rerun the command. Adding this option cannot make a missing binary appear.

5. Put the check in a script

For a pre-flight check, test the exit status and save the output. Do not assume that every line beginning with a version number has the same format:

if perf version >perf-version.txt 2>perf-version.err; then
    printf '%s\n' 'perf is available'
else
    status=$?
    printf 'perf version check failed with status %s\n' "$status" >&2
    sed -n '1,12p' perf-version.err >&2
    exit "$status"
fi

This creates two files in the current directory. Remove them after reviewing them, or choose a temporary directory in your own script. The check does not modify perf configuration, kernel settings or profiling data. If a later step consumes the version, validate that the output is a real version result rather than only checking that a file was created.

For a one-off diagnostic, keep the shell simpler and inspect both streams:

$ perf version 2>&1
$ printf 'exit status: %s\n' "$?"

The second command reports the status of perf version because no intervening command ran. This is a useful checkpoint when the warning is easy to overlook in a longer terminal session.

6. Avoid the common traps

• Confusing the manual name with the command: use perf version; perf-version(1) is the manual page title.
• Reporting the common package as the tool version: linux-tools-common supplies the wrapper and manuals, but the version output comes from the selected perf binary.
• Ignoring the running kernel: the wrapper searches using uname -r. Check that release before choosing a missing package.
• Parsing human output as an API: use the exit status for success or failure, and treat the displayed version and build-option lines as diagnostic text.
• Using root by reflex: reading the version needs no privilege. Elevation belongs to package installation or other system administration, not this check.