{"id":49761272,"url":"https://github.com/nk2552003/mac-cleaner","last_synced_at":"2026-06-06T05:02:22.323Z","repository":{"id":356874608,"uuid":"1234330768","full_name":"NK2552003/Mac-Cleaner","owner":"NK2552003","description":"Detects and removes leftover files from uninstalled apps, stale caches, crash reports, logs, and other system junk — safely, with multiple layers of protection and full undo support.","archived":false,"fork":false,"pushed_at":"2026-05-22T05:16:41.000Z","size":292,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T13:58:33.239Z","etag":null,"topics":["cleaner","macos","macos-package","python","utilities-python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mac-deep-cleaner/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NK2552003.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T03:30:12.000Z","updated_at":"2026-05-22T05:13:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NK2552003/Mac-Cleaner","commit_stats":null,"previous_names":["nk2552003/mac-cleaner"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NK2552003/Mac-Cleaner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NK2552003%2FMac-Cleaner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NK2552003%2FMac-Cleaner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NK2552003%2FMac-Cleaner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NK2552003%2FMac-Cleaner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NK2552003","download_url":"https://codeload.github.com/NK2552003/Mac-Cleaner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NK2552003%2FMac-Cleaner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33969883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cleaner","macos","macos-package","python","utilities-python"],"created_at":"2026-05-11T07:17:31.890Z","updated_at":"2026-06-06T05:02:22.309Z","avatar_url":"https://github.com/NK2552003.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Mac Deep Cleaner\n\n**Reclaim gigabytes of disk space with confidence — the safest, smartest macOS cleanup tool ever built.**\n\n[![PyPI Version](https://img.shields.io/pypi/v/mac-deep-cleaner.svg)](https://pypi.org/project/mac-deep-cleaner/)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/NK2552003/Mac-Cleaner/blob/main/LICENSE)\n[![macOS 10.15+](https://img.shields.io/badge/macOS-10.15+-silver.svg)](https://www.apple.com/macos/)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/mac-deep-cleaner?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=ORANGE\u0026left_text=downloads)](https://pepy.tech/projects/mac-deep-cleaner)\n\n\u003c/div\u003e\n\n**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**.\n\n```bash\n# Two commands, same powerful tool\nmac-cleaner scan    # Full-featured\nmdc scan            # Quick alias\n```\n\n---\n\n## Why Mac Deep Cleaner?\n\n| **Safety First** | **Lightning Fast** | **Smart Detection** |\n|---------------------|----------------------|------------------------|\n| Never touches system files (`com.apple.*`) | Multi-threaded scanning | Bundle ID matching technology |\n| Running apps are protected | Progressively displays results | Team ID validation for containers |\n| Full undo/restore capability | Optimized hashing algorithms | Cross-references 45+ locations |\n| Audit logging for every action | Minimal memory footprint | AI-powered orphan detection |\n\n---\n\n## Installation\n\n### Quick Install (Recommended)\n```bash\npip install mac-deep-cleaner\n```\n\n###  From Source\n```bash\ngit clone https://github.com/NK2552003/Mac-Cleaner.git\ncd Mac-Cleaner\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n---\n\n## Quick Start\n\n### Scan Your System (Safe Preview)\n```bash\nmac-cleaner scan\n```\n\n### Review the Dashboard\n```bash\nmac-cleaner dashboard\n```\n\n### Clean Up (with Undo Support)\n```bash\nmac-cleaner clean          # Interactive mode\nmac-cleaner clean --auto   # Auto-delete detected items\n```\n\n### Need to Restore?\n```bash\nmac-cleaner undo           # Restore last cleanup\n```\n\n---\n\n## Documentation\n\nComprehensive guides for every use case:\n\n| Document | Description |\n|----------|-------------|\n| **[Features Guide](https://github.com/NK2552003/Mac-Cleaner/blob/main/docs/FEATURES.md)** | Complete list of all 60+ features with examples |\n| **[Command Reference](https://github.com/NK2552003/Mac-Cleaner/blob/main/docs/COMMAND_REFERENCE.md)** | Detailed CLI documentation for every command |\n| **[Architecture Guide](https://github.com/NK2552003/Mac-Cleaner/blob/main/docs/ARCHITECTURE.md)** | Internal structure, modules, and extension points |\n| **[PyPI Publishing](https://github.com/NK2552003/Mac-Cleaner/blob/main/docs/PYPI_PUBLISHING.md)** | Build and publish instructions |\n\n---\n\n## Core Features\n\n### Smart Scanning\n- **Orphan Detection** — Finds leftover data from uninstalled apps using bundle ID matching\n- **General Junk** — Caches, logs, crash reports, `.DS_Store`, Xcode artifacts, package manager caches\n- **Developer Junk** — `node_modules`, `venv`, build outputs, coverage dirs (opt-in)\n- **Global Dev Caches** — `~/.npm`, `~/.gradle`, `~/.m2`, `~/.cargo`, `~/.nuget` (opt-in)\n- **Duplicate Finder** — SHA-256 hashing with two-phase optimization, optional APFS clone-aware estimates\n- **Large File Scanner** — Find files ≥100 MB, categorized by type\n- **Broken Symlink Detector** — Scans Homebrew, `/usr/local`, `~/bin`, and more\n\n###  Advanced Cleaning\n- **Browser Data Cleaner** — Cache, cookies, history, sessions (Chrome, Firefox, Safari, Edge, Brave)\n- **iOS Simulator Cleaner** — Manage simulator data and caches\n- **Photos Library Analyzer** — Breakdown of Photos library storage\n- **iOS Backup Finder** — Parse MobileSync backups with device info\n- **Language Pack Stripper** — Remove unused `.lproj` directories\n- **Universal Binary Thinner** — Safely thin fat binaries with `ditto --arch`\n- **Full App Uninstaller** — Remove app bundles plus all associated data\n\n###  Reporting \u0026 Monitoring\n- **Space Map** — Visual disk usage tree\n- **HTML Reports** — Self-contained reports with interactive charts\n- **Scan History** — JSON records with diff comparison\n- **Weekly Digest** — Aggregated weekly summaries\n- **Impact Score** — Measure cleaning effectiveness (0-100)\n- **Storage Trends** — Track disk usage over time\n\n###  System Utilities\n- **System Inspector** — LaunchAgents, LaunchDaemons, login items, SIP status\n- **Memory Pressure Reliever** — Report and purge memory caches\n- **Homebrew Manager** — Cache cleanup, outdated list, autoremove\n- **DNS Cache Flush** — Refresh name resolution\n- **Font Cache Rebuild** — Safely rebuild ATS caches\n- **Spotlight Re-index** — Rebuild metadata index\n- **Power Optimizer** — Apply recommended `pmset` settings\n- **App Update Checker** — System, Homebrew, and App Store updates\n- **PKG Receipt Manager** — List and forget pkgutil receipts\n- **Permissions Auditor** — TCC privacy access audit (read-only)\n- **Time Machine Guard** — Status, age checks, local snapshots\n- **APFS Snapshot Guard** — List and prune local snapshots\n\n###  User Experience\n- **Live TUI Dashboard** — Real-time Rich layout during scans\n- **Interactive TUI Picker** — Keyboard-driven app selection\n- **Shell Completions** — Bash, zsh, fish support\n- **macOS Notifications** — Native notifications via `osascript`\n- **Menu Bar Companion** — SwiftBar/xbar plugin integration\n- **CI Mode** — JSON output with threshold-based exit codes\n- **Undo/Restore** — Staged deletions with checksum verification\n\n###  Cloud \u0026 Security\n- **Cloud Storage Junk** — Dropbox, Google Drive, OneDrive, Box caches\n- **Data Breach Monitor** — HIBP API integration for email checks\n- **Multi-Mac Config Sync** — Export/import configurations\n- **Scheduler** — LaunchAgent for automated weekly scans\n\n---\n\n## Safety Guarantees\n\nMac Deep Cleaner implements **7 layers of protection**:\n\n| Layer | Protection |\n|-------|------------|\n|  **System Protection** | `com.apple.*` files are **NEVER** deleted |\n|  **Running App Guard** | Active applications are automatically protected |\n|  **Group Container Validation** | Team IDs verified against vendor database |\n|  **System Cache Isolation** | OS-owned caches skipped by default |\n|  **Preview by Default** | `scan` command never modifies filesystem |\n|  **Undo/Restore** | Files staged in `~/.mac_cleaner_trash/` for recovery |\n|  **Audit Logging** | Every deletion logged to `~/.mac_cleaner_deleted.log` |\n|  **Final Safety Gate** | Path validation immediately before deletion |\n|  **Binary Backup** | Fat binaries backed up as `.fat_backup` before thinning |\n\n---\n\n##  Common Workflows\n\n### Daily Maintenance\n```bash\n# Quick scan with live dashboard\nmdc dashboard\n\n# Clean up detected items interactively\nmdc clean\n\n# Check system health\nmdc system --health\n```\n\n###  Developer Cleanup\n```bash\n# Scan with developer junk detection\nmdc scan --dev-junk --dev-junk-global\n\n# Clean Xcode derived data\nmdc xcode-cleaner --delete --yes\n\n# Find large project files\nmdc large-files --min-mb 50 --root ~/Projects\n```\n\n### iOS Developer Tools\n```bash\n# List simulators and their sizes\nmdc simulators\n\n# Purge unavailable simulators\nmdc simulators --purge-unavailable --yes\n\n# Manage iOS backups\nmdc extras --ios-backups\n```\n\n### Targeted Cleaning\n```bash\n# Uninstall an app completely\nmdc uninstall \"Slack\"\n\n# Clean specific browser data\nmdc browser-data --browser chrome --category cache --clean\n\n# Find and remove old installers\nmdc installer-hunter --min-age-days 30 --delete --yes\n```\n\n### Reporting \u0026 Automation\n```bash\n# Export scan results\nmdc scan --export report.html\n\n# CI/CD integration\nmdc scan --ci --threshold-mb 500\n\n# Weekly digest\nmdc weekly-digest --days 7\n\n# Compare scans\nmdc diff\n```\n\n---\n\n## Configuration\n\nCreate a config file at `~/.config/mac-cleaner/config.yaml`:\n\n```yaml\n# Active profile\nprofile: developer\n\n# Protected paths\nwhitelist:\n  - ~/Library/Application Support/ImportantApp\n  - ~/Projects/critical-folder\n\n# Categories to skip\nskip_categories:\n  - \"System Cache\"\n  - \"Log File\"\n\n# Custom scan locations\ncustom_scan_roots:\n  - ~/Development\n  - /Volumes/ExternalDrive/Projects\n\n# Scan behavior\nscan_orphans: true\nscan_junk: true\nundo_mode: true\nretention_days: 30\n\n# Thresholds\nlarge_file_threshold_mb: 100\nduplicate_min_size_kb: 4\n\n# Developer options\nscan_dev_junk: true\nscan_dev_junk_global: false\ndev_junk_roots:\n  - ~/Projects\ndev_junk_max_depth: 6\n\n# Custom profiles\nprofiles:\n  minimal:\n    skip_categories:\n      - Xcode Junk\n      - npm Cache\n  aggressive:\n    skip_categories: []\n    large_file_threshold_mb: 50\n    scan_dev_junk_global: true\n```\n\n### Profile Types\n\n| Profile | Best For | Settings |\n|---------|----------|----------|\n| `beginner` | First-time users | Maximum safety, conservative defaults |\n| `developer` | Software engineers | Dev junk enabled, lower thresholds |\n| `professional` | Power users | Aggressive cleaning, all features |\n| `designer` | Creative professionals | Large file focus, media optimization |\n| `minimal` | School/shared devices | Maximum protection, limited scope |\n\n---\n\n## Advanced Commands\n\n### History \u0026 Comparison\n```bash\n# View scan history\nmdc history\n\n# Compare last two scans\nmdc diff\n\n# Compare specific scans\nmdc diff abc12345 def67890\n```\n\n### Undo Operations\n```bash\n# List all undo sessions\nmdc undo --list\n\n# Restore latest session\nmdc undo\n\n# Restore specific session\nmdc undo --session abc12345\n\n# Verify checksums during restore\nmdc undo --verify\n\n# Clean old sessions\nmdc undo --purge\n```\n\n### System Management\n```bash\n# Full system inspection\nmdc system --all\n\n# Memory management\nmdc memory-pressure --relieve\n\n# Purgeable space\nmdc purgeable --thin-gb 10 --yes\n\n# Storage trends\nmdc storage-trend --record\nmdc storage-trend --days 7\n```\n\n### Scheduling \u0026 Automation\n```bash\n# Install weekly scan scheduler\nmdc schedule install\n\n# Check scheduler status\nmdc schedule status\n\n# Remove scheduler\nmdc schedule remove\n```\n\n### Self-Update\n```bash\n# Check for updates\nmdc update --check\n\n# Update automatically\nmdc update --yes\n```\n\n### Config Management\n```bash\n# Initialize config\nmdc config --init\n\n# Show current config\nmdc config --show\n\n# Sync across Macs\nmdc config-sync export\nmdc config-sync import\n```\n\n---\n\n## Example Output\n\n### Scan Summary\n```\n╔══════════════════════════════════════════════════╗\n║         Mac Deep Cleaner - Scan Results          ║\n╠══════════════════════════════════════════════════╣\n║      Orphaned Apps:    23 items  (1.2 GB)        ║\n║      General Junk:     156 items (3.4 GB)        ║\n║      Developer Junk:   42 items  (2.1 GB)        ║\n╠══════════════════════════════════════════════════╣\n║           Total Reclaimable: 6.7 GB              ║\n╚══════════════════════════════════════════════════╝\n\nSafe to clean: 6.5 GB\nReview recommended: 0.2 GB\n```\n\n### Space Map\n```\n/Users (256 GB)\n├── Library (45 GB)\n│   ├── Caches (12 GB)\n│   ├── Application Support (18 GB)\n│   └── Logs (2.3 GB)\n├── Documents (89 GB)\n└── Downloads (34 GB)\n```\n\n---\n\n## Requirements\n\n- **macOS:** 10.15 (Catalina) or later\n- **Python:** 3.9 or higher\n- **Dependencies:** `rich`, `click`, `pyyaml` (auto-installed)\n\n---\n\n## Contributing\n\nWe welcome contributions! Please read our contributing guidelines before submitting PRs.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `pytest tests/`\n5. Submit a pull request\n\n---\n\n## License\n\nCopyright © 2024 Mac Deep Cleaner Contributors\n\nLicensed under the [Apache License 2.0](https://github.com/NK2552003/Mac-Cleaner/blob/main/LICENSE).\n\n---\n\n## Support\n\n-  **Documentation:** [docs/](https://github.com/NK2552003/Mac-Cleaner/tree/main/docs)\n-  **Issues:** [GitHub Issues](https://github.com/NK2552003/Mac-Cleaner/issues)\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the macOS community**\n\n[⭐ Star this repo](https://github.com/NK2552003/Mac-Cleaner) \n[Read the COMMAND REFERENCE](https://github.com/NK2552003/Mac-Cleaner/blob/main/docs/COMMAND_REFERENCE.md) \n[Report an issue](https://github.com/NK2552003/Mac-Cleaner/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnk2552003%2Fmac-cleaner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnk2552003%2Fmac-cleaner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnk2552003%2Fmac-cleaner/lists"}