Smart VAC Cleaner

English · Русский · Eesti · Дед

Portable, safe, modern junk cleaner for Windows. GUI + CLI + Task Scheduler.

Safe by default: dry-run unless you say --delete. All candidate portable roots are always listed in the config; only roots that actually exist on the current machine are swept, and only known junk patterns inside them. Missing drives are silently skipped, never errors.

What it cleans

Layer	What	Where
System	Temp, crash dumps, Explorer thumbnails, Windows Update Cache, DNS cache, Recycle Bin, per-user app caches (100+ AppData targets: browsers, Node/uv/pip caches, VS Code family, Eagle, OBS, Discord...)	%TEMP%, %LOCALAPPDATA%, %APPDATA%
Deep C: Junk	Updater leftovers, *.exe.tmp, Viber QmlWebCache, Yandex.Disk backups, ODIS logs, app.asar.bak and similar	%LOCALAPPDATA%, %TEMP%
Portable roots	Known junk patterns inside portable-app roots you configure	portable_roots in config
Custom rules	Your own path + glob pattern rules	custom_rules in config

Safety (defense in depth)

• Dry-run is physically read-only — GUI "Clean" is real delete (with a confirm dialog), the CLI needs --delete explicitly; a dry-run plans but never mutates (no unlink/chmod/rmdir, no DNS flush, no service stop, no recycle-bin call)
• Blacklist: C:\, C:\Windows, USERPROFILE, Program Files, the script's own folder — these are refused as user-supplied roots (portable/custom): no user root may equal a protected root or be a descendant of one, even if the config asks for it. Reviewed internal system targets (System Temp, AppData caches, …) are not user roots: they carry their own explicitly scoped capability and stay confined to their own per-target SafetyGuard root
• No hardcoded portable roots: fresh config defaults to portable_roots: []
• Min path depth: shallow paths (fewer than 5 parts) are refused
• Running-process check: apps using a target are skipped (per-app process lists); if the process table can't be queried, app-sensitive targets are skipped too (fail closed); the snapshot is refreshed before each destructive app group
• Owner coverage: every AppData target has a verified process owner or is explicitly process-agnostic (shared package/compiler/driver caches) — no implicit owner=None escape hatch
• Symlinks / junctions / reparse points refused; .. segments are canonicalized and the resolved path is confined to the target root and revalidated — a .. that would escape the root is refused
• Never-delete names: login data, bookmarks, cookies, history, trusted_vault.pb, and more — numbered (Cookies (2)) and compound journal (Cookies (2)-wal) variants reduce mechanically to the protected base
• Exclusions: exclude_patterns / exclude_paths in config apply to every deletion (portable, system, custom, deep sweep)
• Backup files: generic .bak rollback artifacts are never auto-deleted
• All deletes go through a SafetyGuard per root; every node under a deleted directory is validated, so protected/excluded subtrees survive; counters advance only after a verified delete; errors are counted, never fatal
• GUI worker threads never touch Tk; closing during a clean cancels and waits for the worker before exiting

Requirements

• Windows 10/11
• Python 3.10+

Install

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Or install as a package (adds the vac-cleaner command):

pip install .
vac-cleaner --status

No Python? Grab SmartVACCleaner.exe from the GitHub Releases tab — fully portable, config and logs live next to the exe. Releases are created automatically from tagged builds by the build-exe workflow; if a version is tagged but has no Release page yet, the workflow has not finished (or the run failed).

Build the exe yourself

powershell -ExecutionPolicy Bypass -File build_exe.ps1

Produces dist\SmartVACCleaner.exe (PyInstaller onefile). On every v* tag, CI builds and uploads the exe as an artifact automatically.

GUI

python _SMART_VAC_CLEANER.py

Seven buttons: Clean (real delete — asks for confirmation first), Stop, Preview (a physically read-only dry-run of what would be deleted), Install Auto-Clean Task, Run in bg (starts a detached silent full clean in the background), Exclusions (edit never-delete patterns and paths), System Targets (opt into risky targets — Recycle Bin, DNS cache, Windows Update cache; persisted in the config). Progress bars per category, full log window; every run also lands in logs\clean_*.log.

CLI

The CLI is dry-run by default — it only reports what would be deleted. Add --delete to actually remove files. --dry-run forces preview even when --delete is present.

Flag	Effect
--cli	Force console mode
--portable / --system / --custom	Select cleaning layers (default: dry-run preview)
--all	All layers at once using safe system-target defaults (Recycle Bin / DNS / Windows Update stay off)
--delete	Real delete (without it the run is a dry-run preview)
--dry-run	Force preview even with --delete
--status	Show how much junk exists per target; nothing is deleted
--analyze-caches	Discover AppData cache folders > 5 MB
--sys-targets	Comma list of system targets to force-enable (System Temp, User Temp, Recycle Bin, ...); unknown names error out
--exclude	Comma list of extra exclude patterns (--exclude "*.db,*.tmp")
--hidden	Hide console window (used by Task Scheduler)
--install-task	Register the daily silent full-clean task
--time HH:MM	Start time for the scheduled task (default 09:00)

Examples:

REM preview everything
python _SMART_VAC_CLEANER.py --cli --all

REM actually delete everything
python _SMART_VAC_CLEANER.py --cli --all --delete

REM preview, then real delete, dry-run flag always wins
python _SMART_VAC_CLEANER.py --cli --all --delete --dry-run

Inspect what would be cleaned:

python _SMART_VAC_CLEANER.py --status

Automated cleanup (Task Scheduler)

python _SMART_VAC_CLEANER.py --install-task --time 09:00

Installs SmartVACCleaner task (highest privileges, hidden window). Uninstall:

schtasks /Delete /TN SmartVACCleaner /F

Configuration

cleaner_config.json is auto-created next to the script (or next to the exe) on first run, with defaults. All paths in it are canonicalized on load: slash style, trailing separators and .. segments are normalized, duplicate roots collapse, protected paths (C:\, Windows, Program Files, user profile, the cleaner's own folder) and nested roots are rejected with a warning. Example:

{
  "portable_roots": ["D:\\Portable"],
  "custom_rules": [{"path": "D:\\Apps\\TestApp", "pattern": "*.log"}],
  "exclude_patterns": ["*.db"],
  "exclude_paths": ["C:\\Users\\me\\AppData\\Local\\Important"],
  "auto_clean_interval_hours": 0,
  "lang": "en"
}

• portable_roots: folders whose known-junk subfolders are swept (pattern-based, e.g. Cache, Temp, Logs, numbered backups). Anything not matching junk patterns is untouched.
• custom_rules: path (folder) + pattern (glob, * = whole contents).
• exclude_patterns / exclude_paths: extra no-go lists.
• lang: GUI language — en (default), ru, et, ded. Built-in strings/*.json live next to the script (or bundled into the exe); drop your own <lang>.json there to add a language.

Tests

python -m pytest -q

Runs offline, touches only temp directories.

Documentation

Full docs live in docs/: Safety, CLI Reference, Configuration, Build & Install, FAQ.

Notes

• Task Scheduler mode needs admin to install the task (/rl HIGHEST).
• Portable roots on non-system drives are cleaned even without admin (VAC pattern).
• This project is not affiliated with any vendor; all paths are well-known app cache/log locations that apps regenerate.