v1.0.2 — Analyze command + accuracy and safety fixes

What's new in v1.0.2

New

• analyze — a read-only command that shows where large app data lives (WhatsApp, Teams, OneDrive, etc.) and how to reclaim it safely inside each app. Never deletes anything.
• find-large --files-only — show only individual files, skipping folders and apps.
• Installer detection — .dmg and .pkg files are flagged as safe to delete after install.

Fixed

• Accurate "last used" dates via Spotlight metadata instead of unreliable filesystem atime (apps no longer falsely show as unused for years).
• Fixed inflated size totals from double-counting nested cache folders.
• Photos/Music library bundles are no longer reported with garbage dates.
• find-large --interactive now moves files to Trash (reversible) instead of permanently deleting.

Compatibility

• Fixed a crash on Python 3.8/3.9 (from __future__ import annotations).
• CI now tests against Python 3.9 and 3.12 on macOS.

Install: uv tool install mac-storage-cleaner

v1.0.1 - Python 3.8/3.9 compatibility + accuracy fixes

fixed crash on Python <3.10, accurate last-used dates via Spotlight metadata, fixed inflated size totals, find-large --interactive now moves files to Trash instead of permanently deleting. Publish it and the workflow ships it to PyPI automatically.

v1.0.0 — Initial Release

mac-storage-cleaner v1.0.0

A fast, safe macOS CLI tool to reclaim disk space.

Features

• clean — removes browser caches, app caches, logs, conda, pip, uv, npm caches
• scan — finds large stale files with color-coded age indicators
• find-large — identifies unused large files in Downloads, Documents, and Applications with interactive deletion
• clean-docker — prunes unused Docker data
• history — shows past cleaning runs
• schedule / unschedule — monthly automated scans with macOS notifications

Install

uv tool install mac-storage-cleaner