PC Cleaner

PC Cleaner is a safe, cross-platform disk analytics tool. It scans a drive or folder and produces an offline HTML dashboard, JSON data, and a complete CSV file inventory. It finds duplicate files and cleanup candidates, but it never deletes or changes user files.

Install

pip install pc-cleaner

PC Cleaner works on Windows, macOS, Linux desktops, WSL, and Linux VPS hosts. On Windows it lists drive letters; on POSIX systems it lists useful mounted filesystems while avoiding virtual kernel mounts such as /proc, /sys, and tmpfs.

Use

Launch the terminal dashboard:

pc-cleaner

The dashboard lists accessible drives with free-space information and includes a folder browser. Select a drive, click a folder to make it the scan target, or type a path manually. While scanning it shows the subprocess output, offers a visible cancel button, and keeps the scan controls disabled until completion.

During scans, the dashboard shows the active phase, elapsed time, indexed file and folder totals, data indexed, and files-per-second rate. Filesystem discovery does not pretend to know an exact completion time; it displays an honest unknown ETA until traversal is complete. Duplicate hashing has a known candidate count, so it shows a real remaining-time estimate. When an HTML report completes, use Open HTML report to open it directly in the default browser.

Check for an update from PyPI:

pc-cleaner update

This asks before installing. After a successful upgrade, restart PC Cleaner to use the new release. For non-interactive automation only, use:

pc-cleaner update --yes

Run from scripts or CI:

pc-cleaner scan --drive D --open
pc-cleaner scan --path "D:\\Projects" --no-dups
pc-cleaner scan --path ~/Downloads --out ./reports
pc-cleaner scan --path /var --out ~/pc-cleaner-reports --no-dups --verbose

Compare two saved reports to see what grew or shrank:

pc-cleaner compare drive_report_D_old.json drive_report_D_new.json
pc-cleaner compare old.json new.json --json

Guard CI against a full volume (exit code 3 when the limit is crossed):

pc-cleaner scan --path D:\ --no-dups --quiet --fail-usage 90

Get ranked, read-only cleanup recommendations (and a script you review yourself):

pc-cleaner advise drive_report_D.json
pc-cleaner advise drive_report_D.json --script cleanup.ps1 --keep shortest
pc-cleaner advise drive_report_D.json --method hardlink --os posix --json

Monitor a volume and alert when it crosses a threshold:

pc-cleaner watch --path D:\ --interval 300 --max-usage 90
pc-cleaner watch --path /var --once --webhook https://example.test/hook

Use PC Cleaner as a library:

from pc_cleaner import api
summary = api.scan(r"D:\\Projects", duplicates=True)
print(summary["totals"]["size"], summary["reclaimable_total"])

Plugins

Drop a *.py file in ~/.pc-cleaner/plugins to add a custom report section:

def analyze(summary):
    return {"title": "My section",
            "html": "<p>Files: %s</p>" % summary["totals"]["files"]}

Use a named scan profile instead of repeating flags:

pc-cleaner scan --path D:\ --profile quick    # skip duplicate hashing + CSV
pc-cleaner scan --path D:\ --profile deep     # hash everything, top 100 rows
pc-cleaner scan --path D:\ --profile dev      # fast pass for developer machines
pc-cleaner scan --path D:\ --profile photos   # size-filtered photo dedupe

Explicit flags always override profile values.

Configuration file

Optional defaults live in ~/.pc-cleaner/config.toml (override with the PC_CLEANER_CONFIG environment variable):

# PC Cleaner configuration
top = 100
threads = 8
min_dup_size = "2MB"
exclude = ["node_modules", ".git", "Windows"]
no_dups = false

[keybindings]
# Rebind dashboard keys (see tui.DEFAULT_BINDINGS for action names)
results = "r"
search = "/"

Exit codes

Structured progress events

In --verbose mode the scanner additionally emits single-line JSON events on stderr, prefixed with #EVT . Automation can consume these instead of scraping human-readable text:

#EVT {"v":1,"kind":"discovery","files":12500,"folders":1200,"bytes":471859200}
#EVT {"v":1,"kind":"dups","done":45,"total":100}

For an Ubuntu/Linux VPS over SSH, use command mode explicitly. If the terminal is not interactive, pc-cleaner will show the equivalent CLI command instead of trying to open a full-screen terminal interface.

The scan produces timestamped HTML, JSON, and CSV reports. The default report location in the TUI is %USERPROFILE%\Documents\PC Cleaner Reports (Windows) or ~/pc-cleaner-reports (Linux/VPS); use --out REPORTS_DIR to choose another.

Features

• Fast, recursive, read-only scans using os.scandir
• Self-contained offline HTML dashboard with sortable tables
• Inline SVG storage treemap and growth-over-time chart (no CDN, no JS libs)
• Dark-mode toggle, global table search, and per-card CSV export (all offline)
• Full CSV file inventory plus JSON, Markdown, and HTML reports
• pc-cleaner compare to diff any two reports (text or --json)
• Cold-data (unused 1y+), old-and-large, and disk-fill forecast insights
• Largest files, folders, extensions, categories, ages, and size buckets
• Duplicate finder using nothing but stdlib hashing (two-stage: cheap head/tail digest first, full BLAKE2b only on real candidates) across a thread pool
• Persistent hash cache so repeat scans skip re-hashing unchanged files
• Multi-target scans (--also) that combine several roots into one report
• .pc-cleanerignore files plus --ignore-file for repeatable exclusions
• Hardlink-aware duplicate detection and sparse/allocated-size accounting
• --estimate for an honest, time-boxed pre-scan scope estimate
• Junk/cache/zero-byte/empty-folder signals
• Ranked cleanup advisor with reclaim estimates and confidence levels
• Dry-run manifest plus review scripts (PowerShell/shell) you inspect and run; --method hardlink suggests reclaiming duplicates without deleting them
• Access-error handling and Windows long-path support
• SQLite-backed processing for very large drives
• Drive chooser and browsable folder tree in the terminal dashboard
• Live results view (largest files seen), with filter and sort
• Scan queue that runs targets back-to-back; favorite targets and saved sessions
• In-log search, activity-log export, and completion notifications + bell
• Profile selector (quick/deep/dev/photos) in the dashboard
• Confirmed PyPI update checker; no automatic restart or silent upgrade
• Cross-platform mount discovery and VPS-safe virtual filesystem exclusions
• Optional --system-scan measuring known Windows/macOS/Linux caches, browser caches, Docker/WSL disks, package caches, and game libraries (read-only)
• Sensitive-file flagging (paths only; contents never read) for .env, keys, etc.
• Custom report sections via drop-in plugins in ~/.pc-cleaner/plugins
• Public in-process Python API (pc_cleaner.api.scan) and optional --webhook
• pc-cleaner watch volume monitor with threshold alerts
• Perceptually similar image finder (--similar-images) with a PNG/BMP average-hash, plus image dimension and EXIF capture-date reading
• Configurable dashboard keybindings ([keybindings]) and mouse support (wheel scrolls the log; click selects list rows) on POSIX terminals

Safety

PC Cleaner is an analysis and recommendation tool. It does not delete, move, modify, or upload your data. Review report findings yourself before performing any cleanup.

License

MIT