Mac Deep Cleaner
Reclaim gigabytes of disk space with confidence — the safest, smartest macOS storage analyzer and cleanup suite.
Mac Deep Cleaner v3.2.0 combines storage analysis, reviewed cleanup, system diagnostics, maintenance, Homebrew package management, and external-disk management in a local dashboard, native macOS app, and command-line tools. File cleanup uses Trash by default; disk formatting and selected maintenance commands are permanent and require a separate review.
Version 3.2.0 adds a dedicated Homebrew manager with dependency explanations, groups, reverse trees, size rankings, update checks, services, and reviewed maintenance. Disks & volumes now hides recovery/system records by default and uses one scrolling page.
# Three convenient commands, same powerful tool
mac-deep-cleaner # Standard entrypoint
mac-cleaner # Alias
mdc # Fast CLI shorthand
Key Highlights
| Safety First | Modern UI & Desktop App | Deep Local Analysis |
|---|---|---|
| Never deletes without review | Responsive dashboard with dark-minimal aesthetic | Intelligent application footprints & leftovers |
| Finder Trash protection by default | Integrated macOS native window chrome & full-screen | Dev toolchains, Docker, caches, logs, Xcode |
| Protected & macOS-managed path guards | Optional Rich & Questionary interactive terminal UI | Duplicate file detection with content hashing |
| Validated scan generations & revisions | No app telemetry; Homebrew can fetch metadata | Fast multi-threaded local scanning |
Ghost Files (experimental)
Open Settings → Experimental → Ghost Files to find possible leftovers from removed apps. It is off by default. Level 1 works offline with deterministic descriptions; level 2 adds local Ollama narration with separate consent for installation, starting the server, and downloading a model (about 1.3–3.4 GB plus Ollama).
Every ghost needs review before moving to Trash through the existing safety pipeline. The model can only make a verdict more cautious. Successful moves appear in an Ofrenda, exportable as Markdown. Remove AI components only offers installations/models created by Mac Deep Cleaner; the shared ~/.ollama directory is retained.
mdc ghosts enable --level 1
mdc ghosts scan --no-llm
mdc ghosts setup --model llama3.2:3b
mdc ghosts disable
See Ghost Files setup, safety, removal, and verification for downloads, local data locations, CLI commands, and discovery limits. The full fresh-account Ollama installation remains a manual release acceptance check.
Installation
Via pip (Recommended)
You can install Mac Deep Cleaner directly from PyPI:
pip install mac-deep-cleaner
To include the optional interactive terminal UI (rich + questionary):
pip install "mac-deep-cleaner[terminal]"
From Source
git clone https://github.com/NK2552003/Mac-Cleaner.git
cd Mac-Cleaner
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
Quick Start & Usage
1. Launch the Interactive Dashboard (Default)
Running without arguments automatically launches the local web UI dashboard on an available loopback port:
mac-deep-cleaner
# or
mac-cleaner
# or
mdc
Options:
mac-cleaner --port 8765 # Custom port
mac-cleaner --no-open # Start server without automatically launching browser
mac-cleaner --apps # Terminal Application Analyzer (optional terminal dependencies)
mac-cleaner --optimize # Open Optimize your Mac
mac-cleaner --disks # Open Disks & volumes
mac-cleaner --homebrew # Open Homebrew management
2. Command-Line & Terminal Mode
Generate non-interactive reports, JSON exports, or run the interactive terminal interface:
# Generate report to stdout
mac-cleaner --report
# Export complete scan report as JSON
mac-cleaner --json storage-report.json --no-interactive
# Interactive terminal UI
mac-cleaner --terminal
# Dry-run safe clean preview
mac-cleaner --clean safe --dry-run
# Execute safe cleanup non-interactively
mac-cleaner --clean safe --yes
Optimize your Mac
The new workspace shows memory pressure, installed memory, swap usage, free storage, battery/power state, uptime, Spotlight status, and a CPU-sorted process sample. Background launch definitions are listed for inspection; they are not presented as a count of running processes. Refresh takes a new sample, and Export report downloads local JSON.
- Everyday maintenance: rebuild Quick Look thumbnails, refresh DNS, rebuild the Spotlight index, and inspect Time Machine snapshots.
- Developer tools: removal of unavailable Xcode simulators, npm cache verification, and a shortcut to developer-file cleanup. Homebrew now has its own workspace.
- macOS controls: open Activity Monitor, Login Items, Storage, Software Update, Battery, Time Machine, Network, or Disk Utility. Settings availability depends on the macOS version.
Each command shows its effects and command details before it starts. Background jobs show completion, output, and failures. DNS and Spotlight use the macOS administrator prompt; credentials are never collected by this app. Spotlight indexing continues after the command returns and can take hours. macOS manages RAM itself; there is no synthetic “boost” score or forced memory purge.
mac-cleaner --health-report # Read-only JSON to stdout
mac-cleaner --health-report --json mac-health.json # Write a health report
mac-cleaner --disk-report # Read-only disk inventory
mac-cleaner --tool brew-cleanup --dry-run # Show the command and effects only
mac-cleaner --tool brew-preview --yes # Ask Homebrew what it would remove
mac-cleaner --tool brew-cleanup --yes --i-understand # Execute permanent maintenance
--tool without --yes asks for terminal confirmation. Permanent maintenance additionally requires a typed phrase or --i-understand. A dry run never runs the maintenance command. Homebrew and npm must already be installed; simulator maintenance requires Xcode. The optional Rich terminal menu retains its cleanup workflows; use the flags above or the dashboard for the new tools.
Homebrew management
Open Homebrew in the sidebar, run mac-cleaner --homebrew, or use mac-cleaner brew dashboard. This is integrated into Mac Deep Cleaner; installing brew-why or Textual is not required.
- Browse requested formulae, dependencies, casks, unknown installation origins, pinned packages, shared dependencies, and reviewed removal candidates.
- Open Why installed? for installed runtime dependencies, retaining roots, and a reverse dependency tree. Dependency groups show which requested applications share a library.
- Rank formulae by Cellar size, check available updates, inspect services, and export JSON or a Brewfile.
- Review upgrades, uninstalls, pin/unpin, install-intent changes, user services, metadata updates, and
brew doctor. - Tidy separates removal of unused dependencies from cache/old-version cleanup. Both require their own previews and confirmations.
The reference commands are available under the app’s command names (all three aliases work):
mac-cleaner brew dashboard
mac-cleaner brew overview
mac-cleaner brew explain openssl@3
mac-cleaner brew heaviest --limit 15
mac-cleaner brew reverse-tree openssl@3
mac-cleaner brew audit
mac-cleaner brew stats
mac-cleaner brew tidy --dry-run
mac-cleaner brew tidy # Interactive review of both steps
mac-cleaner brew export --output Brewfile
mac-cleaner brew overview --json homebrew.json
audit reports available updates using Homebrew metadata; it is not a vulnerability scan. Use mac-cleaner brew update to review a metadata refresh. Removal candidates come from Homebrew’s own autoremove dry run, with additional dependency, pin, and service checks. External scripts can still depend on these packages. See the Homebrew guide for all management commands, safeguards, and measurement limits.
Disks & volumes
The default view shows physical drives, the startup volume, and usable external containers/volumes. Recovery, boot, system-data, VM, and low-level partition records are hidden. Show system volumes reveals them for inspection; their protection remains enforced. Device selection and details share the page’s single scroll area.
Select a drive, APFS container, or volume to inspect capacity, usage, shared free space, mount point, filesystem, encryption, roles, UUID, connection, and SMART status where reported. Startup snapshots are shown separately. APFS space is shared: Other volumes & metadata is the difference between container capacity, container free space, and the selected volume’s usage. Purgeable space is not reported as free space.
| Operation | Availability and effect |
|---|---|
| Verify filesystem / partition map | Runs diskutil verifyVolume / verifyDisk; no repairs. Verification can briefly pause access. |
| Mount / unmount / eject | Eligible external volumes and disks; never force-unmounts. |
| Rename | Eligible external volumes; scripts using the old path may need updating. |
| Add APFS volume | Eligible external APFS containers; shares space without erasing existing volumes. |
| Erase disk | Eligible external physical disks; creates one APFS, case-sensitive APFS, ExFAT, or Mac OS Extended volume using GUID. Permanently erases every volume on that disk. |
| Partition disk | Eligible external physical disks; creates two to four partitions. Specify whole GB for each except the final remainder. Replaces the entire layout and permanently erases all data. |
| First Aid, encryption, resizing | Opens Apple Disk Utility for these advanced operations. |
Erase and partition require a fresh review, a backup acknowledgement, and typing ERASE diskN. Review tokens expire after five minutes and work once. The backend reads fresh disk information and checks identity, topology, eligibility, and the exact command again before execution. Jobs are serialized with cleanup, and changes wait for active scans to finish.
Internal disks, the startup and home filesystems, system-role and detected backup disks, multi-disk containers, virtual disks, read-only media, and unidentified devices cannot be changed by these disk tools. If safety metadata cannot be read, changes are disabled. A blank disk without a stable identity must be initialized in Disk Utility. Backup detection uses APFS roles, configured Time Machine destinations, and mounted legacy backup folders; it cannot identify every unmounted or manually copied backup.
Formatting is not a secure wipe, and it bypasses Trash. Close files, back up the entire target drive, keep the app open, and do not disconnect drives during an operation. If macOS denies ownership or permissions, inspect the error and use Disk Utility; the app does not escalate disk commands automatically. Failed or timed-out operations may have partially completed—refresh and inspect the disk before retrying.
See Apple’s APFS volume guide and partition guide for the difference between shared volumes and fixed partitions.
Native macOS App Build
To build the standalone native .app bundle with the integrated Swift window chrome:
python3 scripts/build_mac.py
The resulting Mac Deep Cleaner.app will be placed in dist/.
Shared App Icon
assets/app_icon.png is the single source for the app's branding. The dashboard and browser favicon serve this image directly; the native build generates its .icns file from it without adding another background or changing its proportions. Python distributions include the same asset inside mac_deep_cleaner/assets/. Replace the source PNG and rebuild to update all of these surfaces.
Cleanup & Safety Rules
- Cleanup Defaults: Ordinary file cleanup moves files to Finder's Trash. Disk erase/repartition and explicitly reviewed maintenance commands do not use Trash. Trash moves do not immediately increase free disk space until Trash is emptied.
- Strict Verification: The backend verifies scan generation tokens, exact file IDs, inode matches, and path restrictions before performing any changes.
- System Protection: System files (
com.apple.*, SIP paths, running app bundles) are strictly locked and protected. - Privacy & Permissions: For full analysis of user caches and containers, grant Full Disk Access to Terminal (or Mac Deep Cleaner) in System Settings → Privacy & Security → Full Disk Access.
Development & verification
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
python3 -m build
Disk safety and job tests inject a fake command runner. They never erase, partition, unmount, or maintain the host Mac. Optional browser checks also use this fixture:
npm install --prefix /tmp/mdc-ui-check playwright
/tmp/mdc-ui-check/node_modules/.bin/playwright install chromium
PYTHONPATH=. python3 tests/toolkit_fixture.py
# In a second terminal:
NODE_PATH=/tmp/mdc-ui-check/node_modules node tests/verify_toolkit.cjs
# Restart the fixture between suites to reset its simulated installation:
NODE_PATH=/tmp/mdc-ui-check/node_modules node tests/verify_homebrew.cjs
The browser suites check review/execute flows, cancellation, backup acknowledgement, dependency protection, Homebrew exports, hidden system volumes, absence of nested disk scrolling, and narrow layouts. Read-only live diagnostics can be checked with --health-report and --disk-report. Destructive operations still require a disposable physical test drive for hardware validation; fixture tests cannot establish hardware reliability. The Homebrew formula source version is updated, but its existing checksum placeholder must be replaced with the published archive’s actual checksum before distribution.
License
Distributed under the Apache 2.0 License. See LICENSE for more information.
Metadata
Release files for mac-deep-cleaner 3.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mac_deep_cleaner-3.2.0.tar.gz | 367.6 kB | Without provenance | Details for mac_deep_cleaner-3.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mac_deep_cleaner-3.2.0-py3-none-any.whl | Python 3 | none | any | Details for mac_deep_cleaner-3.2.0-py3-none-any.whl |
Total release size: 692.6 kB
Release files / mac_deep_cleaner-3.2.0.tar.gz
| Download URL | mac_deep_cleaner-3.2.0.tar.gz |
|---|---|
| Size | 367.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
484bfecd607a81c552a8146eefd43061dd3c7713a6c47018d6913d86292c02c5
|
|
BLAKE2b-256 checksum How to use checksums |
5735a17d997a1b79ee2b42b1cf45b13de4b23d47e707ccdd77f6843d0e955089
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / mac_deep_cleaner-3.2.0-py3-none-any.whl
| Download URL | mac_deep_cleaner-3.2.0-py3-none-any.whl |
|---|---|
| Size | 325.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e57584dc20d92fc5721db0f1ee6c520c07cf75eb9a5262d456ff8bf2a8743405
|
|
BLAKE2b-256 checksum How to use checksums |
f47626779d4da6538cbdbb1255e96e2abcb65ca800ab9e260632d3d27ba3c3ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for mac-deep-cleaner 3.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.