PSTACK(1) General Commands Manual PSTACK(1)

# [NAME](#NAME)

`pstack` — print stack traces from Linux processes and core files

# [SYNOPSIS](#SYNOPSIS)

`pstack` \[`-Aa`] \[`-b` `delay`] \[`-e` `executable`] \[`-g` `directory`] \[`-jlnstuvY`] \[`-M` `frames`] \[`-o` `file`] \[`-r` `depth`] \[`-x` `command`] \[`-R`] \[`-p`] \[`executable` | `pid` | `core`] `...`

`pstack` \[`-p`] \[`-l`] \[`-m`] \[`-A`] `pid` | `core`

# [DESCRIPTION](#DESCRIPTION)

`pstack` prints a stack trace for every thread in a running Linux process or an ELF core file. It reads ELF, DWARF, and call-frame information directly, and can therefore unwind code compiled with `-fno-omit-frame-pointer` as well as code that omits frame pointers when suitable unwind data is present.

The target operands may be PIDs or core files. Normally, `pstack` infers the executable from the target. An ELF file given as an operand that is not a core becomes the executable to use for the following targets, until another executable is given. The `-e` option sets that executable explicitly.

More than one target may be supplied. ELF and DWARF data shared by targets are cached for the duration of the invocation.

Tracing a live process requires permission to use [ptrace(2)](/man/os/pstack/ptrace.2). Distribution ptrace policies, containers, and the target's security settings may prevent tracing even when the tracer and target have the same UID.

The options are as follows:

[`-a`](#a), `--args`

Attempt to show function argument values. This is best-effort and requires usable DWARF information and readable target memory.

[`-A`](#A), `--all`

Show both CPython and native DWARF stack traces. Without this option, `-p` prints only the Python trace.

[`-b`](#b) `delay`, `--constant` `delay`

Repeat the trace until interrupted, waiting `delay` seconds between iterations. `delay` may be non-integral.

[`-D`](#D) `elf-file`, `--dwarf-dump` `elf-file`

Print DWARF information from `elf-file` as JSON and exit.

[`-d`](#d) `elf-file`, `--elf-dump` `elf-file`

Print ELF information from `elf-file` as JSON and exit.

[`-e`](#e) `executable`, `--executable` `executable`

Use `executable` as the executable image for subsequent PID or core operands.

[`-g`](#g) `directory`, `--debug-dir` `directory`

Add `directory` to the search path for debug files for executables and shared libraries.

[`-h`](#h), `--help`

Print a usage summary and exit.

[`-j`](#j), `--json`

Write stack traces as JSON rather than text. The JSON representation is intended for automation, but consumers should pin the `pstack` version because its schema is not a separately versioned interface.

[`-l`](#l), `--locals`

Print local variables in Python stack frames. This option is meaningful with `-p`.

[`-M`](#M) `frames`, `--max-frames` `frames`

Print at most `frames` stack frames for each thread.

[`-m`](#m), `--python-modules`

Request the contents of Python modules while tracing. This is retained for the legacy Python inspector and is generally not needed by the modern remote CPython inspector.

[`-n`](#n), `--no-ext-debug`

Do not load external debug information. In particular, do not follow debug links or look for separate debug images.

[`--no-buildid`](#no-buildid)

Do not search for executable or debug files by GNU build ID.

[`--no-local-files`](#no-local-files)

Do not assume files visible to the tracer match the target's view, and do not open local files.

[`-o`](#o) `file`, `--output` `file`

Write normal output to `file` instead of standard output.

[`-p`](#p), `--python`

Print stack traces from compatible CPython interpreters found in the target. When built with modern Python remote-debugging support, this reads interpreter state from the target and uses version- and architecture-matched offset data.

[`-r`](#r) `depth`, `--depth` `depth`

Set the maximum nesting depth when rendering Python values.

[`-R`](#R), `--debuginfod`

Use the debuginfod client to fetch missing executable and debug files by build ID. This requires a usable libdebuginfod.so.1 at run time and a configured debuginfod service.

[`-s`](#s), `--no-src`

Do not include source file and line information in stack frames.

[`-t`](#t), `--no-threaddb`

Do not use `thread_db` to enumerate pthreads; enumerate kernel LWPs instead.

[`-v`](#v), `--verbose`

Produce additional diagnostic output. This option may be repeated.

[`-V`](#V), `--version`

Print the build version and exit.

[`-x`](#x) `command`, `--command` `command`

Run `command` as a subprocess and trace it when it receives a signal. No target operand is required with this option.

[`-Y`](#Y), `--no-die-names`

Do not use DWARF DIE names for functions.

[`--build-id-debugpath`](#build-id-debugpath) `directory`

Add `directory` to the build-ID search path for debug files.

[`--build-id-exepath`](#build-id-exepath) `directory`

Add `directory` to the build-ID search path for executable files.

[`--clear-search-paths`](#clear-search-paths)

Remove the built-in executable and debug-file search paths. Use this before supplying explicit search paths to inspect files from another system.

[`--exe-dir`](#exe-dir) `directory`

Add `directory` to the search path for executables and shared libraries.

[`--freeres`](#freeres)

Free all allocated memory before exit. This is primarily useful when running `pstack` under Valgrind or a heap checker.

# [CPYTHON OFFSET DATA](#CPYTHON_OFFSET_DATA)

The modern CPython inspector requires an offset-data file named pyoff-<version>-<architecture>.json. Installed data is searched through the current directory and XDG data locations. Use `pstack-mkpyoff` with a target libpython to generate data for a compatible interpreter version that is not already provided. Use `-v` to report the selected file.

# [GO GOROUTINE OFFSET DATA](#GO_GOROUTINE_OFFSET_DATA)

Parked Go goroutine traces require an offset-data file named gooff-<major>.<minor>-<architecture>.json. A file generated with one patch release is used for its Go minor series. The installed data is searched through the current directory and XDG data locations. Use `pstack-mkgooff` with a Go executable containing DWARF to generate data for its Go runtime. When Go is available at build time, the go-offset-probe build target creates a suitable local executable.

# [DEBUG INFORMATION](#DEBUG_INFORMATION)

Unwinding normally needs .eh\_frame or .debug\_frame. Symbols, source locations, and argument values improve when matching debug packages are available. By default, `pstack` searches standard debug locations, follows .gnu\_debuglink, and uses GNU build IDs. The `-g`, `--exe-dir`, and build-ID-path options add search locations; alternatively, `-R` can obtain missing data from debuginfod.

# [FILES](#FILES)

/usr/lib/debug

A default root for separate debug files.

/usr/lib/debug/.build-id

A default root for debug files located by build ID.

/usr/lib/.build-id

A default root for executable files located by build ID.

# [EXIT STATUS](#EXIT_STATUS)

The `pstack` utility exits 0 on success, and >0 if an error occurs.

# [SEE ALSO](#SEE_ALSO)

[proc(5)](/man/os/pstack/proc.5), [ptrace(2)](/man/os/pstack/ptrace.2)

# [AUTHORS](#AUTHORS)

Peter Edwards

August 25, 2026 Linux

---

Document: pstack(1) from pstack 2.18.7-r0 (Chainguard OS)
Source: https://github.com/peadar/pstack