mac-storage-cleaner 1.0.2

A fast, safe macOS CLI tool to reclaim disk space

mac-storage-cleaner

A fast, safe macOS CLI tool to reclaim disk space by removing known junk files and identifying large stale items.

Features

• clean — deletes browser caches (Chrome, Firefox, Safari), app caches in ~/Library/Caches, conda package caches, log files in ~/Library/Logs, and developer caches (pip, uv, npm); prompts for confirmation before deleting (bypass with --yes)
• --dry-run flag — shows exactly what would be deleted and how much space would be freed, without touching anything
• scan — finds files and folders larger than a configurable size that haven't been accessed in over 90 days (configurable), printing them as warnings
• find-large — scans ~/Downloads, ~/Documents, and /Applications for large, unused items; shows type (App, ZIP archive, Installer, Folder, Video, Image, Document, or File) with context-specific cleanup tips
• analyze — read-only report showing the largest items inside ~/Library/Group Containers, ~/Library/Containers, and ~/Library/Application Support, with per-app guidance on how to reclaim space safely without deleting files directly
• clean-docker — removes unused Docker containers, images, volumes, and build cache via docker system prune
• history — displays a table of past cleaning runs with totals and per-category breakdown
• schedule / unschedule — installs or removes a monthly launchd job that runs a dry-run scan on the 1st of each month at 9am and sends a macOS notification

Requirements

• macOS
• uv (brew install uv)

Installation

# Install from GitHub
uv tool install "git+https://github.com/prithvikochhar/Mac_Storage_Cleaner"

Or install from a local clone:

uv tool install .

Or run without installing:

uv run mac-storage-cleaner <command>

Usage

Preview what would be cleaned (safe — no deletions)

mac-storage-cleaner clean --dry-run

Actually clean junk files

mac-storage-cleaner clean
# You will be prompted to confirm before any files are deleted.
# To skip the prompt (e.g. in scripts):
mac-storage-cleaner clean --yes

After cleaning, a disk space summary is always printed (both dry-run and real runs):

Free space: 45.2 GB → 52.7 GB (freed 7.5 GB)

For dry-run, the estimated free space after is shown instead.

Clean only specific categories

# Clean only browser/app caches and log files
mac-storage-cleaner clean --categories caches,logs

# Clean only developer tool caches
mac-storage-cleaner clean --categories developer

# Clean everything including Docker (adds docker system prune)
mac-storage-cleaner clean --categories caches,logs,conda,developer,docker

Available categories: caches, logs, conda, developer, docker.
If --categories is not specified, all categories except docker are cleaned (default behaviour unchanged).
A note is printed at the top showing which categories are active.

Exclude specific apps or cache folders from clean

# Skip Spotify and Chrome caches
mac-storage-cleaner clean --exclude Spotify,Chrome

# Combine with other flags
mac-storage-cleaner clean --dry-run --exclude npm,pip

Matching is case-insensitive against any component of the path. Skipped items are shown in yellow with a skipped (excluded) note.

Find large stale files (default: >1 GB, not accessed in 90+ days)

mac-storage-cleaner scan

Scan with custom thresholds

# Find items larger than 500 MB not accessed in 60+ days
mac-storage-cleaner scan --min-size 500MB --days 60

# Scan a specific directory
mac-storage-cleaner scan --path ~/Downloads --min-size 100MB

Find large unused items in Downloads, Documents, and Applications

mac-storage-cleaner find-large

This scans:

• ~/Downloads and ~/Documents — items >100 MB not accessed in 30+ days
• /Applications — apps >500 MB not opened in 180+ days

Each result shows its type (App, ZIP archive, Installer, Folder, Video, Image, Document, or File) with a context-specific note:

• ZIP archives are flagged as likely safe to delete
• Installer files (.dmg, .pkg) are flagged as safe to delete after the app is installed
• Apps remind you to drag to Trash in Finder (not just delete)
• Old folders in Downloads prompt you to inspect before deleting

Output ends with a How to clean these up: guide.

# Customize thresholds for Downloads/Documents
mac-storage-cleaner find-large --min-size 200MB --days 60

# Show only individual files — skip directories and the Applications scan
mac-storage-cleaner find-large --files-only
# or: mac-storage-cleaner find-large -f

# Interactively delete items one by one
mac-storage-cleaner find-large --interactive
# or: mac-storage-cleaner find-large -i

After showing the results table, --interactive prompts for each non-app item:

Move to Trash? ~/Downloads/old-backup.zip [y/n/q(uit)]: 

• y moves the item to Trash (recoverable by emptying Trash in Finder) and prints how much will be reclaimable
• n skips to the next item
• q exits the interactive session without moving remaining items
• Items inside /Applications are always skipped with a reminder to use Finder
• A summary is printed at the end showing how many items were moved and how much space is reclaimable

Note: find-large --interactive moves files to Trash (reversible). The clean command permanently deletes caches and logs, which is appropriate because those files are always regenerable.

Analyze where space is used (read-only)

mac-storage-cleaner analyze

analyze is completely read-only — it never deletes anything. It scans the three directories where macOS apps store their data:

• ~/Library/Group Containers
• ~/Library/Containers
• ~/Library/Application Support

For each section it prints the top 10 entries above 100 MB (largest first), with a safe, app-specific tip for reclaiming the space:

App	How to reclaim space
WhatsApp	Settings ▸ Storage and Data ▸ Manage Storage
OneDrive	Preferences ▸ enable Files On-Demand / Free up space
Dropbox	Preferences ▸ enable Online-only / Smart Sync
Google Drive	Settings ▸ Stream files (don't mirror)
Microsoft Teams	Settings ▸ clear cache
Slack	Preferences ▸ Advanced ▸ Reset cache
Spotify	Settings ▸ Storage ▸ clear cache
Docker	mac-storage-cleaner clean-docker
Everything else	Manage inside the app's own settings

Why not just delete these files? App containers often hold databases, indexes, and sync state. Deleting them directly can corrupt the app or force a full re-download. Use the in-app controls instead — they know what is safe to remove.

View cleaning history

mac-storage-cleaner history

Displays a table of every past clean run with timestamp, total freed, and per-category breakdown. The log is stored at ~/.mac-storage-cleaner/history.log.

Schedule monthly scans

# Install a launchd job: runs a dry-run scan on the 1st of each month at 9am
# and sends a macOS notification when complete
mac-storage-cleaner schedule

# Check whether the scheduler is installed
mac-storage-cleaner schedule --status

# Remove the scheduler
mac-storage-cleaner unschedule

The notification reads: "Monthly scan complete. Run mac-storage-cleaner history to see results."

Clean up unused Docker data

# See what would be freed (no deletions)
mac-storage-cleaner clean-docker --dry-run

# Actually prune unused Docker data
mac-storage-cleaner clean-docker

Requires Docker to be installed and Docker Desktop to be running. If Docker is not installed the command prints a notice and exits cleanly.

Help

mac-storage-cleaner --help
mac-storage-cleaner clean --help
mac-storage-cleaner scan --help
mac-storage-cleaner find-large --help
mac-storage-cleaner analyze --help
mac-storage-cleaner clean-docker --help
mac-storage-cleaner history --help
mac-storage-cleaner schedule --help

What gets cleaned

Category	Paths
Chrome cache	~/Library/Caches/Google/Chrome, ~/Library/Application Support/Google/Chrome/Default/Cache
Firefox cache	~/Library/Caches/Firefox
Safari cache	~/Library/Caches/com.apple.Safari, ~/Library/Safari/LocalStorage
App caches	All subdirectories of ~/Library/Caches
Conda cache	~/Library/Caches/conda, ~/.conda/pkgs (only if present)
Log files	All items in ~/Library/Logs
Developer caches	pip, uv, and npm caches (only for tools that are installed)

Tip: Always run --dry-run first to preview what will be deleted.

Development

# Install dependencies
uv sync

# Run during development
uv run mac-storage-cleaner clean --dry-run