Configure perf settings safely with perf-config

Use perf config to inspect or change the settings that perf reads from its configuration files. This guide shows how to make a reversible per-user change, check the result, and understand when a setting belongs in the system file instead.

The route

Jump straight to the step you need, or tick off Done means at the end.

Checkpoint: identify the file and current values
Checkpoint: make a reversible user change
Choose values that match the data
System-wide settings and privileges
Undo a change and isolate problems

You need the perf command from linux-tools-common, plus the matching kernel-specific Linux tools package for your running kernel. Allow about 10 minutes for a small user configuration change. The examples write only to your own ~/.perfconfig unless a command is explicitly marked as system-wide.

Checkpoint: identify the file and current values

Check that the command is available.
```
perf --version
perf config --list
```
The first command prints the installed perf version. The second lists current configuration names and values from all sections. If the wrapper reports that perf is not available for the running kernel, install the matching tools package before continuing. Do not assume that linux-tools-common alone supplies a usable binary for every kernel.
Look up one setting without changing anything.
```
perf config call-graph.record-mode
```
A configured value such as fp, dwarf or lbr is printed. An unset value may produce no useful value, depending on the perf build. Query several names together when comparing a configuration:
```
perf config report.queue-size call-graph.order report.children
```

By default, perf reads both the system configuration and the user configuration. The user file is $HOME/.perfconfig. The system file is the perf installation's $(sysconfdir)/perfconfig, commonly under /etc, but the exact path is chosen when perf is built. Use --user or --system when you need to make that scope explicit.

Checkpoint: make a reversible user change

Set a report option in your user configuration.
```
perf config --user report.sort-order=srcline
```
This writes the setting to ~/.perfconfig. It affects commands that use report sorting; it does not rewrite existing perf.data files. Verify the stored value:
```
perf config --user report.sort-order
```
Use the exact section and variable spelling from the manpage. Configuration names are written as section.name, while the file itself uses a section header followed by an indented variable.
Set more than one user value in one command when the changes belong together.
```
perf config --user ui.show-headers=false annotate.hide_src_code=true
```
The first value hides column headings in the TUI for report and top. The second suppresses source lines in annotate where that browser supports the option. These are display preferences, so they are reasonable per-user settings. A setting may appear to do nothing when you are using a different browser, such as stdio instead of TUI.

Choose values that match the data

For call graphs, fp uses frame pointers, dwarf uses DWARF unwinding when the required library support is present, and lbr works only on suitable CPUs. The kernel's own unwinder configuration controls kernel-space unwinding. A setting in perf config cannot overcome missing hardware or library support.

perf config --user call-graph.record-mode=fp
perf config --user call-graph.print-type=graph
perf config --user call-graph.order=caller

The call-graph print type can be graph, fractal, flat or folded. The order setting controls how call chains are printed. These values change presentation or recording defaults, not the permissions needed to collect kernel performance data.

The build ID cache is another setting worth treating carefully. Perf normally keeps files needed for later symbol resolution in $HOME/.debug. To move that cache, set an explicit directory:

perf config --user buildid.dir=/var/tmp/perf-debug

Choose a directory with suitable ownership and capacity. Setting buildid.dir=/dev/null disables the cache, which can make later analysis lose the binaries or symbols it needs. That is a deliberate trade-off, not a cleanup shortcut.

System-wide settings and privileges

Use the system scope only when every user of the machine should receive the same default:

sudo perf config --system report.percent-limit=1
sudo perf config --system report.percent-limit

The command needs elevated privileges because it writes the system-wide perf configuration. It may also read only that location, rather than merging the user file. Avoid putting personal colour or TUI preferences in the system file. A system change can affect scripts, analysts and services that run perf under other accounts.

Before a broad change, record the current value:

perf config --system report.percent-limit

If the query is empty, that does not necessarily mean the effective value is zero. It can mean the setting is absent and perf will use its built-in default. The manpage documents several such defaults, including a 500 millisecond process-map timeout and an 8192-byte DWARF stack dump size.

Undo a change and isolate problems

Restore a previous value by setting it again.
```
perf config --user report.sort-order=comm,dso,symbol
perf config --user report.sort-order
```
For a setting that should no longer be present, edit ~/.perfconfig and remove only its variable line. Make a backup first:
```
cp -- ~/.perfconfig ~/.perfconfig.before-perf-config
editor ~/.perfconfig
```
If the edit causes trouble, restore the backup with cp -- ~/.perfconfig.before-perf-config ~/.perfconfig. This is a file-level recovery, so inspect the path before copying if another process may have changed it.
Temporarily bypass configuration when diagnosing a surprising result.
```
PERF_CONFIG=/dev/null perf config --list
```
PERF_CONFIG=/dev/null disables configuration-file reading. It can also name an alternate configuration file. This affects only the command launched with that environment variable. Do not put it in a shell profile unless you intend to disable perf configuration for every later command.

Done means

perf --version runs with tools matching the running kernel.
You inspected the effective list or queried the exact setting.
User changes were written with --user and verified by querying them.
System changes, if any, were intentional, recorded and run with sudo.
You know how to restore the old value or the backed-up configuration file.

For the complete variable list and build-specific file path, read perf-config(1) on the target machine. The available variables can differ when optional perf libraries or browsers were not detected at build time.