The most elegant way to keep your Linux system lean and mean. Inspired by Mole on macOS.
Topo requires Linux, Python 3.10 or newer, curl, gpg, and the Python packaging library.
gpg verifies the signed release during script installation and before every topo update, which
refuses to run unverified without it. DEB/RPM installations resolve these dependencies through the
system package manager. For script installation or running directly from a source checkout, install
them first if needed:
sudo apt install python3 curl gpg python3-packaging # Debian / Ubuntu
sudo dnf install python3 curl gnupg2 python3-packaging # Fedora / RHEL
sudo zypper install python3 curl gpg2 python3-packaging # openSUSE / SLES
sudo pacman -S python curl gnupg python-packaging # Arch / ManjaroThe script installer checks these runtime requirements before installing Topo. This repository
is not currently distributed as a Python wheel, so pip install . is not a supported installation
method.
Script Installation (Recommended)
curl -fsSL https://github.com/Jesencloud/Topo/releases/latest/download/install.sh | bashFor a reproducible installation, replace vX.Y.Z with a release that includes the installer,
then pin both the installer and target version:
curl -fsSL https://github.com/Jesencloud/Topo/releases/download/vX.Y.Z/install.sh | bash -s -- --version vX.Y.ZPackage Manager (.deb / .rpm)
Download from the latest release, then install via:
sudo apt install ./topo_xxx-1_amd64.deb # Debian / Ubuntu
sudo dnf install ./topo-xxx-1.x86_64.rpm # Fedora / RHELSupported Architectures:
amd64/x86_64&arm64/aarch64. Arch Linux users please use the script installer.
⠶⣶⠶ ⢰⠶⡆ ⢰⠶⡆ ⢰⠶⡆
⠿ ⠸⠤⠇ ⢸⠉⠁ ⠸⠤⠇ ● v1.x.x is digging deeper 🦡
Main Menu
> 1. Clean Free up disk space
2. Uninstall Remove apps completely
3. Optimize Check and maintain system
4. Analyze Explore disk usage
5. Status Monitor system health
↑/↓ | M: Mute | Enter: Select | ESC: QuitSafely remove package manager caches, journal logs, developer build artifacts, and system caches.
$ topo clean
➤ System & Package Manager
✓ Cleaned DNF cache (1.2 GB)
✓ Vacuumed journal logs (218 MB)
➤ Developer Tools & AI Models
✓ Cargo cache (44.5 MB) cleaned
Total space freed: 1.25 GB | Free space now: 482.2 GBInteractively select applications to remove. Topo automatically traces and purges all associated config files, caches, and residues.
$ topo uninstall
Select Application to Remove
✓ 1. brave-browser 428.7 MiB
✓ 2. Thunderbird 368.7 MBPowered by a high-speed Rust engine, scan hundreds of thousands of files in milliseconds to explore storage hogs.
$ topo analyze
Exploring: /home/users/.config/Cursor
○ 1. ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬ 59.9% 📁 WebStorage | 109.4 MiB
○ 2. ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬ 6.8% 📁 Cache | 12.4 MiBTrack deletion events and audit what changed after a cleanup or uninstall. Each session is shown
newest first: a header line (started -> ended command), a counts line (removed / trashed /
skipped / failed and total size), and up to three of its paths.
$ topo history --limit 5
Deletion History
2026-06-05T09:12:40+08:00 -> 2026-06-05T09:12:48+08:00 clean
✓ removed=2 - trashed=0 ◎ skipped=1 - failed=0 size=508.0 MiB
✓ removed ~/.cache/pip
✓ removed ~/.cache/thumbnails
◎ rejected-user-writable-ancestor /var/tmp/portage
2026-06-04T18:17:01+08:00 -> 2026-06-04T18:17:03+08:00 uninstall wechat
- removed=0 ✓ trashed=1 - skipped=0 - failed=0 size=820.0 MiB
✓ trashed ~/.local/share/wechatOptional. topo does not create ~/.config/topo/config.json for you — write it by hand to change a default. Every key is optional; anything missing or invalid falls back to the value below.
{
"config_version": 2,
"use_trash": true,
"min_age_days": 0,
"show_scrollbar": true,
"theme_color": "purple"
}| Key | Default | Meaning |
|---|---|---|
use_trash |
true |
Where a recoverable deletion goes. Editor backups, orphaned cache remnants, app residue, zombie autostart entries, broken user symlinks, and user-owned paths deleted from topo analyze are trashed; set it to false to wipe them instead. Irreplaceable app data (including sandbox data under ~/.var/app and ~/snap) always goes to the trash. Routine cache/temp cleanup is always permanent, as is topo analyze deletion that requires administrator access. |
min_age_days |
0 |
A floor, in days, under which nothing is old enough to be cleaned. Each cleaner keeps its own window (30 days for caches, 7 for editor backups, 3 for /tmp); this can only push one further into the past, never closer to now. 0 leaves every threshold where the code put it. |
show_scrollbar |
true |
Draw the scrollbar in the interactive selectors. |
theme_color |
purple |
Title color: purple, cyan, blue, magenta, green, yellow or red. --no-color and NO_COLOR still win. |
Keep "config_version": 2 in the file. A config without it is read as one written by topo ≤ 1.1.2, where min_age_days and theme_color had no effect at all: those two values are dropped rather than suddenly honoured, so upgrading never moves an existing install off the thresholds and title color it has always had.
Add your own paths to the protection whitelist and no cleaner — nor topo analyze — will touch them:
topo whitelist add ~/Projects # `list` and `remove` take the same formA recoverable deletion (see use_trash) goes to your desktop trash via gio or trash-cli; restore it from your file manager, or with gio trash --restore / trash-restore. Routine cache cleanup and admin-level topo analyze deletions are permanent.
For scripting, clean/optimize/remove accept --dry-run, every command returns standard exit codes (0 ok, 1 failure/refusal, 2 bad args, 130/143 signals, 141 closed pipe), and on networked filesystems scan concurrency can be capped with TOPO_IO_THREADS=1. See topo --help for the details.
- Safety First: Built-in global whitelist protecting system binaries, user credentials, and XDG folders.
- High-Speed Engine: Python flexibility paired with Rust raw speed for ultra-fast file scanning.
- Terminal Friendly: Uses Alternate Screen Buffer to preserve your shell session history upon exit.
MIT License. Developed with ❤️ for the Linux community.