Linux repositories inspector


March 2018


A tool for generating flame graphs for Python (2) processes.


pyflame - A Ptracing Python Profiler


B]pyflame] [B]options]] [B]-p]|B]--pid]] I]PID]
B]pyflame] [B]options]] [B]-t]|B]--trace]] I]command] [I]args]...]


B]pyflame] is a Python profiler that created flame graphs. It uses B]ptrace](2) to extract stack information. The output of B]pyflame] is intended to be used with Brendan Gregg[aq]s I]] script, which can be found on GitHub at <>.


There are two invocation forms. When B]-p] I]PID] is used, pyflame will attach to the running process specified by I]PID] to collect profiling data. The meaning of this option is analogous to its meaning in commands like B]strace](1) or B]gdb](1).
When B]-t] is given, pyflame will instead go into "trace mode". In this mode, it interprets the rest of the command line as a command to run, and traces the command to completion. This is analogous to how B]strace](1) works when a PID is not specified.
B]-d], B]--dump]
Dump stacks from all threads (implies B]--threads]).
B]-h], B]--help]
Display a friendly help message.
B]-o], B]--output]=I]FILENAME]
Write profiling output to I]FILENAME] (otherwise stdout is used).
B]-p], B]--pid]=I]PID]
Specify which I]PID] to trace.
Older versions of pyflame received I]PID] as a positional argument, where I]PID] was interpreted as the last argument. This usage mode still works, but is considered deprecated. You should use B]-p] or B]--pid] when specifying I]PID].
B]-s], B]--seconds]=I]SECONDS]
Profile the process for duration I]SECONDS] before detaching. The default is to profile for 1 second. This option is not compatible with trace mode.
B]-r], B]--rate]=I]RATE]
Sample the process at this frequency. The argument I]RATE] is interpreted as a fractional value, measured in seconds. For example, B]-r 0.1] would mean to sample the process every 0.1 seconds (i.e. every 100 milliseconds). The default value for I]RATE] is 0.01, which samples every ten milliseconds.
Note that setting a low value for rate will increase the accuracy of profiles, but it also increases the overhead introduced by pyflame. The default frequency used by pyflame is relatively aggressive; a less aggressive value like B]-r 0.01] may be more appropriate if you are profiling processes in production.
B]-t], B]--trace] I]command] [I]args]...]
Run pyflame in trace mode, which traces the child process until completion. If used, this must be the final argument (the rest of the arguments will be interpreted as a command plus arguments to the command). This is analogous to B]strace](1) in its default mode.
B]-v], B]--version]
Print the version.
B]-x], B]--exclude-idle]
Exclude "idle" time from output.
Enable profiling multi-threaded Python apps.


The following options are less commonly used.
Force a particular Python ABI. This option should only be needed in edge cases when profiling embedded Python builds (e.g. uWSGI), and only if pyflame doesn[aq]t automatically detect the correct ABI. I]VERSION] should be a two digit integer consisting of the Python major and minor version, e.g. 27 for Python 2.7 or 36 for Python 3.6.
Print the timestamp for each stack. This is useful for generating "flame chart" profiles. Generally regular flame graphs are encouraged, since the timestamp flame charts are harder to use.


You can find the complete documentation online at: <>. The online documentation is more comprehensive than this man page, and includes usage examples.


If you find any bugs, please create a new issue on GitHub: <>


Evan Klitzke <>.
⇧ Top