pystack

1.6.0 verified Mon Apr 27 auth: no python

pystack is a command-line tool developed by Bloomberg for analyzing the stack of remote Python processes. It attaches to a running Python process (supporting Python >=3.7) and dumps the Python stack frames, including local variables and source references, without requiring debug symbols or ptrace. The current version is 1.6.0, with a stable maintenance release cadence.

pip install pystack

Common errors

error pystack: error: argument PID: invalid integer value: 'abc' ↓

cause Non-numeric PID argument passed to pystack CLI.

fix

Provide a valid integer process ID. Example: pystack 1234

error pystack: Process 1234 not found ↓

cause The target PID does not exist or pystack cannot access it.

fix

Verify the process exists: ps aux | grep 1234. Check permissions and ptrace settings.

error OSError: [Errno 1] Operation not permitted ↓

cause Insufficient permissions to attach to the process (e.g., ptrace restrictions).

fix

Run as root or temporarily disable ptrace_scope: echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Warnings

breaking pystack requires the target Python process to have a compatible version (>=3.7). Attaching to an older Python version will fail. ↓

fix Ensure target process uses Python >=3.7. Use `pystack --version` to check compatible versions.

gotcha Running pystack on a process that is not a Python process or on a non-Linux platform will produce confusing errors. ↓

fix Verify target is a Python process and OS is Linux (official support). Use `file /proc/<pid>/exe` to check.

gotcha pystack requires permissions to attach to a remote process (e.g., same user or ptrace scope). Without them, it fails silently or with 'No such process'. ↓

fix Run as root or adjust ptrace settings: `echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`

Imports

pystack
```
import pystack
```
pystack is a command-line tool; the Python module is typically used via subprocess or CLI. Importing is valid but uncommon.

Quickstart

Run pystack via CLI from Python. The tool must be installed and the process must be a Python process >=3.7.

import subprocess
import os

# Attach to a Python process by PID (replace 1234)
result = subprocess.run(['pystack', '1234'], capture_output=True, text=True)
print(result.stdout)