diskcleanup

A safety-first disk cleanup toolkit for Windows. It finds and proposes, you approve, and only then does it act — reversibly. Nothing is ever deleted without an explicit --execute, and even then items are moved to a quarantine you can restore from, never hard-deleted. Space is freed only when you purge.

It's built for messy, full drives — especially developer + creative workstations — where the space is hidden across caches, duplicates, stale project folders, and multiple versions of the same app.

scan ──▶ report ──▶ (you approve) ──▶ apply --execute ──▶ purge
 read-only  md+html     choose what       move to quarantine    free space
                                                 │
                                                 └──▶ restore   (undo anytime before purge)

⚠️ Use at your own risk. This tool moves and removes files. It is designed to be conservative and reversible, but you are responsible for reviewing what it proposes. Read the Safety model. No warranty (MIT).

---

Why

cleanmgr and "Storage Sense" only scratch the surface. On a real working machine the space is buried in places they don't touch:

• gigabytes of build/package caches (npm, pip, cargo, NuGet, …)
• duplicate exports, renders, and downloads
• stale project folders you forgot about
• 5 versions of Blender, 3 Visual Studio installs, old SDKs
• 70 GB of pagefile + hibernation you may not need

diskcleanup measures all of it from the actual on-disk byte counts (not the unreliable Windows "EstimatedSize"), shows you exactly what and why, and lets you reclaim it safely.

Features

• 🔍 Real measurements. Whole-drive map via WizTree (reads the NTFS MFT — seconds, not minutes), analysed with multithreaded polars.
• 🧹 Categorised cleanup from a 99-rule knowledge base: temp, OS/dev/browser/app caches, logs, old versions, duplicates (via multithreaded czkawka), stale folders, and large files.
• 🔬 Deep audit: full disk accounting, installed-software inventory with real last-used dates (UserAssist), and multi-version / redundant install detection.
• ♻️ Reversible by design. Removals are moved to a quarantine (optionally on another drive, which frees the cleaned drive immediately) with an auto-written restore guide. restore to undo, purge to finalize.
• 🛡️ Two-gate safety guard validates every path independently of the rules — it will not touch system files, credentials, registry hives, your documents, or folders you mark as work.
• 📄 Human-readable reports (Markdown + a self-contained HTML dashboard).

Safety model

1. Dry-run by default. scan, report, audit, and apply (without --execute) never change the filesystem.
2. Two-mode path guard (safety.py), applied to every concrete path at apply time, independent of the rules:
   • cache mode (cache/temp rules): the path must sit under a small allow-list of reclaimable roots, and not under any protected subtree — including your own Documents/Desktop/Pictures.
   • user mode (stale/duplicate cleanup you explicitly approve): user files are allowed, except credentials (.ssh, .gnupg, .aws, …), registry hives (NTUSER.DAT, *.regtrans-ms), system files, and your configured work dirs.
   • Reparse points (junctions/symlinks) and too-shallow paths are always refused.
3. Reversible removal. Items are moved to the quarantine via an instant same-volume rename (or a cross-volume move that frees the source drive now). restore puts them back; purge deletes them for good. Every run writes a _RESTORE.md next to the data and logs/RESTORE-<run-id>.md.
4. Programs are never auto-removed. Unused/old apps are flagged with evidence; you uninstall them yourself.

Requirements

• Windows 10/11, Python 3.10+
• WizTree (free for personal use) — disk mapping
• czkawka_cli — duplicate detection

winget install -e --id AntibodySoftware.WizTree
winget install -e --id qarmin.czkawka.cli

Install

git clone https://github.com/dprvda/diskcleanup
cd diskcleanup
py -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt

Quick start

# 1. Read-only scan: maps the drive, finds reclaimable space, writes the report.
.\.venv\Scripts\python -m diskcleanup scan
#    -> open out\report.html  (grouped, with size, risk, and a reason per item)

# 2. Preview what a safe cleanup would remove (still no changes):
.\.venv\Scripts\python -m diskcleanup apply --categories temp,os-cache,dev-cache,browser,app-cache --max-risk safe

# 3. Do it (moves to quarantine, reversible):
.\.venv\Scripts\python -m diskcleanup apply --categories temp,os-cache,dev-cache,browser,app-cache --max-risk safe --execute

# 4. Confirm nothing broke, then free the space for good:
.\.venv\Scripts\python -m diskcleanup runs
.\.venv\Scripts\python -m diskcleanup purge --run <RUN_ID> --yes
#    ...changed your mind? undo:  python -m diskcleanup restore --run <RUN_ID>

Example summary:

Disk C:  146.9 GB free of 931.4 GB
  safe-to-reclaim      :   3.6 GB
  reclaim-after-review :  61.9 GB
  advisory (flagged)   : 136.2 GB

  temp          32.6 GB  (965 items)
  duplicates    23.2 GB  (1760 items)
  stale         31.3 GB  (114 items)
  dev-cache     10.0 GB
  app-cache      4.9 GB
  ...

Commands

Command	What it does
scan	read-only: map the drive, detect reclaimables, write report + manifest
report	re-render report.md / report.html from the last scan
stale	list old/stale folders (--days, --min-mb), work dirs excluded
audit	deep software+disk audit: versions, real last-used, full accounting
apply	approve & move items to quarantine — dry-run unless --execute
runs	list quarantine runs
restore --run <id>	move a run's items back
purge --run <id> --yes	permanently delete a run's quarantined items

apply filters: --categories, --max-risk safe\|review\|risky (default safe), --source, --ids, --recycle (use the Recycle Bin instead of quarantine).

Configuration

All machine-specific settings go in a git-ignored diskcleanup.local.json (or environment variables) — copy the example and edit:

copy diskcleanup.local.example.json diskcleanup.local.json

{
  // Folders to NEVER touch and to skip in stale/duplicate analysis
  "exclude_dirs": ["%USERPROFILE%\\Dropbox", "%USERPROFILE%\\Documents\\my-project"],
  // Put quarantine on another drive to free the cleaned drive immediately
  "quarantine_dir": "D:\\DiskCleanupQuarantine"
}

Env-var equivalents: DISKCLEANUP_EXCLUDE (path-separated list), DISKCLEANUP_QUARANTINE, DISKCLEANUP_DRIVE, DISKCLEANUP_HOME, WIZTREE_EXE.

How the audit works (and its limits)

audit cross-references the WizTree map with installed-program registry entries and Windows UserAssist launch history to find redundant installs and apps you haven't opened. Two honest caveats baked into the output:

• Sizes come from the disk map, never the registry EstimatedSize (which some installers populate with garbage — e.g. a 142 MB app claiming 39 GB).
• "no launch record" ≠ "never used." UserAssist only logs Explorer/Start launches, so the audit flags candidates for you to confirm — it never auto-removes apps.

Project layout

diskcleanup/
  config.py      paths, tool locations, thresholds, local-config loader
  safety.py      the two-mode path guard (unit-tested)
  wiztree.py     WizTree runner + polars CSV parser
  czkawka.py     duplicate / big-file runner (read-only)
  programs.py    installed-program inventory + old-version detection
  stale.py       old/stale-artifact detection
  audit.py       deep software + disk audit
  scan.py        scan orchestrator -> out/manifest.json
  report.py      manifest -> out/report.md + report.html
  quarantine.py  apply / restore / purge engine
  cli.py         command-line interface
  data/kb.json   knowledge base (99 reclaim rules + protected paths)
out/             scan artifacts (git-ignored)
logs/            per-run action logs for rollback (git-ignored)

Contributing

Issues and PRs welcome — especially new knowledge-base rules for apps/caches in diskcleanup/data/kb.json (each rule has a path, method, risk, and rationale). Please don't include machine-specific paths or personal data.

License

MIT. Provided as-is, without warranty. Built with WizTree, czkawka, and polars.