🦡 Topo

High-performance system optimization and cleanup for Linux.

The most elegant way to keep your Linux system lean and mean. Inspired by Mole on macOS.

Requirements

Topo requires Linux, Python 3.10 or newer, curl, and the Python packaging library. 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 python3-packaging       # Debian / Ubuntu
sudo dnf install python3 curl python3-packaging       # Fedora / RHEL
sudo pacman -S python curl python-packaging           # Arch / Manjaro

The 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.

Quick Start

Script Installation (Recommended)

curl -fsSL https://raw.githubusercontent.com/Jesencloud/Topo/main/install.sh | bash

Package Manager (.deb / .rpm)

Download from the latest release, then install via:

sudo apt install ./topo_xxx_amd64.deb   # Debian / Ubuntu
sudo dnf install ./topo-xxx-1.x86_64.rpm  # Fedora / RHEL

Supported Architectures: amd64/x86_64 & arm64/aarch64. Arch Linux users please use the script installer.

---

Features

Main UI ( Type 'Topo' in your terminal to get started )

 ⠶⣶⠶  ⢰⠶⡆ ⢰⠶⡆ ⢰⠶⡆
  ⠿   ⠸⠤⠇ ⢸⠉⠁ ⠸⠤⠇   ● 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: Quit

1. One-Key Deep Cleanup (topo clean)

Safely 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 GB

2. Smart App Uninstaller (topo uninstall)

Interactively 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 MB

3. Disk Usage Explorer (topo analyze)

Powered 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 MiB

4. Audit & History (topo history)

Track deletion events and audit what changed after a cleanup or uninstall.

$ topo history --limit 5
2026-06-04T18:17:03+08:00  uninstall wechat  size=820.4 MiB

---

Highlights

• 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.

License

MIT License. Developed with ❤️ for the Linux community.