Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them.
Features
- Memory overview - Real-time total/used/free/swap display
- Multiple views - All, Orphaned, Killable, Process Groups, High Memory
- Orphan detection - Finds processes whose parent died (PPID=1)
- Killable detection - Orphans safe to kill (not tmux, not system services)
- Stale detection - Flags processes with deleted executables
- Tmux awareness - Won't flag tmux processes as orphan candidates
- Batch operations - Select multiple processes and kill them at once
- Process grouping - Find duplicate/similar processes consuming resources
- Custom columns - Select which columns to display in CLI output
- Configurable thresholds - Adjust memory filters via CLI flags
- Preview mode - Dry-run for kill operations with formatting options
- CLI mode - Scriptable commands with JSON/CSV/Markdown output
- Clickable TUI - Click headers to sort, rows to select
Installation
pip install procclean
Or with uv (recommended):
uv tool install procclean
Or with pipx:
pipx install procclean
Run without installing:
uvx procclean
# or
pipx run procclean
Usage
TUI Mode (default)
procclean
CLI Commands
# List processes
procclean list # List processes (table)
procclean ls # Alias for 'list'
procclean list -f json|csv|md # Different output formats
procclean list -s mem|cpu|pid|name|cwd # Sort by field
procclean list -a # Sort ascending (default: descending)
procclean list -o # Orphans only
procclean list -m # High memory only (>500MB)
procclean list -k # Killable orphans only
procclean list --cwd # Filter by current directory
procclean list --cwd /path/to/dir # Filter by specific cwd
procclean list -n 20 # Limit output to 20 processes
procclean list -c pid,name,rss_mb # Custom columns
procclean list --min-memory 10 # Only processes using >10 MB
procclean list --high-memory-threshold 1000 # High-mem at 1000 MB
# Process groups
procclean groups # Show process groups
procclean g # Alias for 'groups'
procclean groups -f json # Groups as JSON
# Kill processes
procclean kill <PID> [PID...] # Kill process(es)
procclean kill -f <PID> # Force kill (SIGKILL)
procclean kill --cwd /path -y # Kill all in cwd (skip confirm)
procclean kill -k -y # Kill all killable orphans
procclean kill -k --preview # Preview what would be killed
procclean kill -k --dry-run # Alias for --preview
procclean kill -k --preview -O json # Preview in JSON format
# Memory summary
procclean mem # Show memory summary
procclean memory # Full name for 'mem'
procclean mem -f json # Memory info as JSON
TUI Keybindings
| Key | Action |
|---|---|
q |
Quit |
r |
Refresh |
k |
Kill selected (SIGTERM) |
K |
Force kill (SIGKILL) |
o |
Show orphans |
O |
Show killable |
a |
Show all |
g |
Show groups |
w |
Filter by selected cwd |
W |
Clear cwd filter |
Space |
Toggle selection |
s |
Select all visible |
c |
Clear selection |
1 |
Sort by memory |
2 |
Sort by CPU |
3 |
Sort by PID |
4 |
Sort by name |
5 |
Sort by cwd |
! |
Reverse sort order |
Click column headers to sort, click rows to toggle selection.
Views
- All Processes - All user processes sorted by memory usage
- Orphaned - Processes with PPID=1 (parent died)
- Killable - Orphans safe to kill (not in tmux, not system services)
- Process Groups - Similar processes grouped together
- High Memory - Processes using >500MB RAM (configurable)
Output Formats
CLI supports multiple output formats via -f:
table- Human-readable table (default)json- JSON array for scriptingcsv- CSV for spreadsheetsmd- Markdown table
Custom Columns
Use -c to specify which columns to display:
procclean list -c pid,name,rss_mb,cwd
Available columns: pid, name, rss_mb, cpu_percent, cwd, ppid,
parent_name, status, cmdline, username
Requirements
- Python 3.14+
- Linux (uses
/procfilesystem)
Development
git clone https://github.com/kjanat/procclean
cd procclean
uv sync
uv run pre-commit install --install-hooks
Run tests:
uv run pytest # All tests
uv run pytest --cov -vv # With coverage
Lint and type check:
uv run ruff check src/
uv run ty check
License
Metadata
Release files for procclean 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| procclean-2.0.1.tar.gz | 22.8 kB | Without provenance | Details for procclean-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| procclean-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for procclean-2.0.1-py3-none-any.whl |
Total release size: 52.7 kB
Release files / procclean-2.0.1.tar.gz
| Download URL | procclean-2.0.1.tar.gz |
|---|---|
| Size | 22.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8532ab7df9a844f70c07241d377d0927f284f7446545acc24b51956bb033c90
|
|
BLAKE2b-256 checksum How to use checksums |
18c5571796818d8eedc42191d80a2ac35a8d0e6d5d6c3cd59026db28ec8fc312
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / procclean-2.0.1-py3-none-any.whl
| Download URL | procclean-2.0.1-py3-none-any.whl |
|---|---|
| Size | 29.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15f0901fdceacd71ce5a46f321f1660ff106fffe4c587d9663a5e3f231afdba3
|
|
BLAKE2b-256 checksum How to use checksums |
6373112eca959d9d816c271607e00023e3a9a25cf9c5da1a8228955ec6395c31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for procclean 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.