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.
• t: run live py-spy top for the selected process.
• 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.

Live top is available for one selected process at a time. For multiprocessing and torchrun/DDP sibling ranks, use group recording.

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. It also runs just verify-dist, which fails unless dist/ contains only wheels and includes the required macOS and Linux manylinux x86_64/aarch64 wheel tags.

Build a local wheel:

just dist-local

Linux release wheels are built as manylinux wheels with Zig so they work on most supported Linux distributions:

just dist-linux-x86_64
just dist-linux-aarch64

Check release artifacts without rebuilding:

just verify-dist