Reclaim gigabytes of disk space with confidence — the safest, smartest macOS cleanup tool ever built.
Mac Deep Cleaner is a professional-grade macOS utility that intelligently detects and removes leftover files from uninstalled apps, stale caches, crash reports, logs, and system junk — with multiple layers of protection and full undo support.
# Two commands, same powerful tool
mac-cleaner scan # Full-featured
mdc scan # Quick alias| Safety First | Lightning Fast | Smart Detection |
|---|---|---|
Never touches system files (com.apple.*) |
Multi-threaded scanning | Bundle ID matching technology |
| Running apps are protected | Progressively displays results | Team ID validation for containers |
| Full undo/restore capability | Optimized hashing algorithms | Cross-references 45+ locations |
| Audit logging for every action | Minimal memory footprint | AI-powered orphan detection |
pip install mac-deep-cleanergit clone https://github.com/NK2552003/Mac-Cleaner.git
cd Mac-Cleaner
python3 -m venv .venv
source .venv/bin/activate
pip install -e .mac-cleaner scanmac-cleaner dashboardmac-cleaner clean # Interactive mode
mac-cleaner clean --auto # Auto-delete detected itemsmac-cleaner undo # Restore last cleanupComprehensive guides for every use case:
| Document | Description |
|---|---|
| Features Guide | Complete list of all 60+ features with examples |
| Command Reference | Detailed CLI documentation for every command |
| Architecture Guide | Internal structure, modules, and extension points |
| PyPI Publishing | Build and publish instructions |
- Orphan Detection — Finds leftover data from uninstalled apps using bundle ID matching
- General Junk — Caches, logs, crash reports,
.DS_Store, Xcode artifacts, package manager caches - Developer Junk —
node_modules,venv, build outputs, coverage dirs (opt-in) - Global Dev Caches —
~/.npm,~/.gradle,~/.m2,~/.cargo,~/.nuget(opt-in) - Duplicate Finder — SHA-256 hashing with two-phase optimization
- Large File Scanner — Find files ≥100 MB, categorized by type
- Broken Symlink Detector — Scans Homebrew,
/usr/local,~/bin, and more
- Browser Data Cleaner — Cache, cookies, history, sessions (Chrome, Firefox, Safari, Edge, Brave)
- iOS Simulator Cleaner — Manage simulator data and caches
- Photos Library Analyzer — Breakdown of Photos library storage
- iOS Backup Finder — Parse MobileSync backups with device info
- Language Pack Stripper — Remove unused
.lprojdirectories - Universal Binary Thinner — Safely thin fat binaries with
ditto --arch - Full App Uninstaller — Remove app bundles plus all associated data
- Space Map — Visual disk usage tree
- HTML Reports — Self-contained reports with interactive charts
- Scan History — JSON records with diff comparison
- Weekly Digest — Aggregated weekly summaries
- Impact Score — Measure cleaning effectiveness (0-100)
- Storage Trends — Track disk usage over time
- System Inspector — LaunchAgents, LaunchDaemons, login items, SIP status
- Memory Pressure Reliever — Report and purge memory caches
- Homebrew Manager — Cache cleanup, outdated list, autoremove
- DNS Cache Flush — Refresh name resolution
- Font Cache Rebuild — Safely rebuild ATS caches
- Spotlight Re-index — Rebuild metadata index
- Power Optimizer — Apply recommended
pmsetsettings - App Update Checker — System, Homebrew, and App Store updates
- PKG Receipt Manager — List and forget pkgutil receipts
- Permissions Auditor — TCC privacy access audit (read-only)
- Time Machine Guard — Status, age checks, local snapshots
- APFS Snapshot Guard — List and prune local snapshots
- Live TUI Dashboard — Real-time Rich layout during scans
- Interactive TUI Picker — Keyboard-driven app selection
- Shell Completions — Bash, zsh, fish support
- macOS Notifications — Native notifications via
osascript - Menu Bar Companion — SwiftBar/xbar plugin integration
- CI Mode — JSON output with threshold-based exit codes
- Undo/Restore — Staged deletions with checksum verification
- Cloud Storage Junk — Dropbox, Google Drive, OneDrive, Box caches
- Data Breach Monitor — HIBP API integration for email checks
- Multi-Mac Config Sync — Export/import configurations
- Scheduler — LaunchAgent for automated weekly scans
Mac Deep Cleaner implements 7 layers of protection:
| Layer | Protection |
|---|---|
| System Protection | com.apple.* files are NEVER deleted |
| Running App Guard | Active applications are automatically protected |
| Group Container Validation | Team IDs verified against vendor database |
| System Cache Isolation | OS-owned caches skipped by default |
| Preview by Default | scan command never modifies filesystem |
| Undo/Restore | Files staged in ~/.mac_cleaner_trash/ for recovery |
| Audit Logging | Every deletion logged to ~/.mac_cleaner_deleted.log |
| Final Safety Gate | Path validation immediately before deletion |
| Binary Backup | Fat binaries backed up as .fat_backup before thinning |
# Quick scan with live dashboard
mdc dashboard
# Clean up detected items interactively
mdc clean
# Check system health
mdc system --health# Scan with developer junk detection
mdc scan --dev-junk --dev-junk-global
# Clean Xcode derived data
mdc xcode-cleaner --delete --yes
# Find large project files
mdc large-files --min-mb 50 --root ~/Projects# List simulators and their sizes
mdc simulators
# Purge unavailable simulators
mdc simulators --purge-unavailable --yes
# Manage iOS backups
mdc extras --ios-backups# Uninstall an app completely
mdc uninstall "Slack"
# Clean specific browser data
mdc browser-data --browser chrome --category cache --clean
# Find and remove old installers
mdc installer-hunter --min-age-days 30 --delete --yes# Export scan results
mdc scan --export report.html
# CI/CD integration
mdc scan --ci --threshold-mb 500
# Weekly digest
mdc weekly-digest --days 7
# Compare scans
mdc diffCreate a config file at ~/.config/mac-cleaner/config.yaml:
# Active profile
profile: developer
# Protected paths
whitelist:
- ~/Library/Application Support/ImportantApp
- ~/Projects/critical-folder
# Categories to skip
skip_categories:
- "System Cache"
- "Log File"
# Custom scan locations
custom_scan_roots:
- ~/Development
- /Volumes/ExternalDrive/Projects
# Scan behavior
scan_orphans: true
scan_junk: true
undo_mode: true
retention_days: 30
# Thresholds
large_file_threshold_mb: 100
duplicate_min_size_kb: 4
# Developer options
scan_dev_junk: true
scan_dev_junk_global: false
dev_junk_roots:
- ~/Projects
dev_junk_max_depth: 6
# Custom profiles
profiles:
minimal:
skip_categories:
- Xcode Junk
- npm Cache
aggressive:
skip_categories: []
large_file_threshold_mb: 50
scan_dev_junk_global: true| Profile | Best For | Settings |
|---|---|---|
beginner |
First-time users | Maximum safety, conservative defaults |
developer |
Software engineers | Dev junk enabled, lower thresholds |
professional |
Power users | Aggressive cleaning, all features |
designer |
Creative professionals | Large file focus, media optimization |
minimal |
School/shared devices | Maximum protection, limited scope |
# View scan history
mdc history
# Compare last two scans
mdc diff
# Compare specific scans
mdc diff abc12345 def67890# List all undo sessions
mdc undo --list
# Restore latest session
mdc undo
# Restore specific session
mdc undo --session abc12345
# Verify checksums during restore
mdc undo --verify
# Clean old sessions
mdc undo --purge# Full system inspection
mdc system --all
# Memory management
mdc memory-pressure --relieve
# Purgeable space
mdc purgeable --thin-gb 10 --yes
# Storage trends
mdc storage-trend --record
mdc storage-trend --days 7# Install weekly scan scheduler
mdc schedule install
# Check scheduler status
mdc schedule status
# Remove scheduler
mdc schedule remove# Check for updates
mdc update --check
# Update automatically
mdc update --yes# Initialize config
mdc config --init
# Show current config
mdc config --show
# Sync across Macs
mdc config-sync export
mdc config-sync import╔══════════════════════════════════════════════════╗
║ Mac Deep Cleaner - Scan Results ║
╠══════════════════════════════════════════════════╣
║ Orphaned Apps: 23 items (1.2 GB) ║
║ General Junk: 156 items (3.4 GB) ║
║ Developer Junk: 42 items (2.1 GB) ║
╠══════════════════════════════════════════════════╣
║ Total Reclaimable: 6.7 GB ║
╚══════════════════════════════════════════════════╝
Safe to clean: 6.5 GB
Review recommended: 0.2 GB
/Users (256 GB)
├── Library (45 GB)
│ ├── Caches (12 GB)
│ ├── Application Support (18 GB)
│ └── Logs (2.3 GB)
├── Documents (89 GB)
└── Downloads (34 GB)
- macOS: 10.15 (Catalina) or later
- Python: 3.9 or higher
- Dependencies:
rich,click,pyyaml(auto-installed)
We welcome contributions! Please read our contributing guidelines before submitting PRs.
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
pytest tests/ - Submit a pull request
Copyright © 2024 Mac Deep Cleaner Contributors
Licensed under the Apache License 2.0.
- Documentation: docs/
- Issues: GitHub Issues
Made with ❤️ for the macOS community