py-spy-tui

A Rust terminal UI for py-spy, packaged so users can install it with:

pip install py-spy-tui
py-spy-tui

py-spy-tui depends on the py-spy Python package, so installing the TUI also installs the profiler binary on supported platforms.

Current Features

• Groups Python processes by distributed training metadata, process tree, runtime prefix, working directory, and command fingerprint.
• Detects virtualenv, uv-managed Python, Conda, pyenv, and system runtimes.
• Shows PyTorch rank metadata when process environment is readable.
• Explains Linux rootless profiling setup before asking sudo to attach to a process.
• Uses sudo -v for authentication and never reads or stores a password.

Usage

py-spy-tui

Non-interactive checks:

py-spy-tui --help
py-spy-tui --version

Keys:

• Enter: record the selected process or process group for 30 seconds.
• d: run py-spy dump for the selected process or process group.
• r: refresh process groups.
• Space: expand or collapse a group.
• j / k or arrow keys: move selection.
• PageUp / PageDown: scroll output.
• q: quit.

When a group is selected, py-spy-tui runs one py-spy command per process. This is useful for torchrun and distributed PyTorch training, where ranks are often sibling processes rather than children of a single attach target.

Reports

Every record run creates a recognizable report folder in the current directory:

py-spy-report-<target-name>-<unix-timestamp>/
  raw/
    pid-1234.svg
    pid-1235.svg
  report.md
  report.json

The raw/ folder keeps py-spy's original SVG records. report.md is written for humans, and report.json is structured so you can pass the folder to an LLM and ask it to compare hot frames, rank imbalance, blocking stacks, and data-loading stalls.

Linux Rootless Profiling

Attaching to an existing process often requires elevated permissions on Linux. To allow same-user profiling without sudo:

sudo sysctl kernel.yama.ptrace_scope=0

To keep that setting after reboot:

echo 'kernel.yama.ptrace_scope=0' | sudo tee /etc/sysctl.d/10-py-spy-tui.conf
sudo sysctl --system

This changes system-wide ptrace policy for same-user debugging. Use sudo from the TUI when you prefer not to change the host setting.

Build

Local full check:

just build-all

That runs formatting, tests, clippy, clears dist/, builds a wheel, and smoke-checks it.

Build a local wheel:

uv build --wheel

Linux release wheels should be built as musllinux so they do not require the target machine's glibc version:

just dist-linux-x86_64-musl