ptop3

An htop-like TUI process monitor that groups processes by application.

Screenshots

Main group view — processes grouped by application

Detail view — individual processes for a selected group

Tree view — process hierarchy within a group

Features

• Groups processes by application name with smart alias resolution
• Colored header with memory, swap, load-average badges
• Sort by memory, CPU, RSS, swap, I/O, or count
• Regex filter across app name, process name, and cmdline
• Process tree view within a selected application group
• Kill signals (SIGTERM / SIGKILL) for individual processes or entire groups
• w key: clean swap by cycling swapoff/swapon (passwordless sudo)
• d key: drop kernel caches (passwordless sudo)
• Alerts for high CPU, memory, swap, disk usage, and zombie processes
• Lite mode (--lite) for lower overhead on busy systems

Installation

pip install ptop3

Quick Start

ptop3                 # interactive TUI
python -m ptop3       # same via module
ptop3 --once          # print one-shot table and exit
ptop3 --filter python # filter to python processes

Sudo Setup

The w (swap-clean) and d (drop-caches) keys require root. Configure passwordless sudo once:

sudo ptop3 --init-subscripts

Or manually:

sudo visudo -f /etc/sudoers.d/ptop3
# Add:
# YOUR_USER ALL=(root) NOPASSWD: /path/to/ptop3-drop-caches
# YOUR_USER ALL=(root) NOPASSWD: /path/to/ptop3-swap-clean

Check sudo status:

ptop3 --check-sudo

CLI Reference

Key Bindings

Subscripts

The privileged subscripts can also be run directly:

ptop3-drop-caches --help
ptop3-drop-caches --level 1 --dry-run

ptop3-swap-clean --help
ptop3-swap-clean --safety-mb 256 --dry-run

Development

git clone https://github.com/spazyCZ/ptop3
cd ptop3
pip install -e ".[dev]"
pytest
ruff check ptop3/

Branching Strategy

feature/xyz  ──PR──►  test  ──PR──►  main  ──tag v*.*.*──►  release

CI / CD

Release Process

1. Merge all feature PRs into test and verify on TestPyPI:

   pip install -i https://test.pypi.org/simple/ ptop3
   

2. Bump the version (run on test):

   bump-my-version bump patch   # or minor / major
   git push origin test
   

3. Open a PR from test → main and merge once CI is green.
4. Tag the release on main:

   git tag v0.x.y
   git push origin v0.x.y
   

   This creates the GitHub Release automatically.
5. Publish to PyPI manually: Actions → Publish to PyPI → Run workflow — enter the tag.