My Mac said 179.58 GB of 245.11 GB used. Applications made sense. Documents made sense. But a huge gray block labeled System Data took up more space than everything else combined, and macOS wouldn't tell me what was inside it.
I got tired of guessing, so I decided to build something that would show me everything and let me act on it. The next few days looked a lot like this:
How it came together
The first version was a plain CLI, built with a bit of help from my friend, AI.
It worked, but only just. It listed files under 10 MB, had no color, and nothing was organized.
So I went back and looked for libraries that could present the output properly, and rich was a big help. The second version was decent, but it still felt like something was missing.
Next I wondered whether the output could be interactive. It turned out I could connect a web interface to the Python side and route everything through it. That was a real improvement, but still not quite there.
A bit more digging showed me I could wrap that web interface in a native window. That's how it became a proper macOS app, which I built for myself first.
Then I opened Mac Deep Cleaner, the tool I'd made for exactly this problem, and let it scan my own machine.
It found a lot. More importantly, it showed me where every gigabyte lived, so I didn't have to guess. That's the whole idea: a cleaner that opens the box and lets you decide, instead of deleting things you never got to see.
The one rule
Never delete anything the user hasn't reviewed.
Everything else grew out of that sentence:
- Files go to Finder's Trash, not straight into oblivion.
- Before anything moves, every cleanup is checked against scan generation tokens, exact file IDs, inode matches, and path restrictions.
- System files (
com.apple.*, SIP-protected paths, running app bundles) are locked and can't be touched. - There's no cloud analytics. Everything runs on your machine.
What the scan found on my Mac
When you launch it, you get a local dashboard that tells you the truth right away.
Across 68 items, it found 34.63 GB that could be reclaimed. The split underneath that headline number matters more:
- Safe to remove: 41.39 MB
- Review first: 32.90 GB
- Needs care: 1.69 GB
I could have made that headline far more exciting by auto-selecting everything. Instead, only the tiny safe slice is one click away. The big chunk is marked "Review first" because the tool can't know what matters to you, and I think that honesty is the whole point of the product.
Seeing inside your apps
The part I'm proudest of is the Application Analyzer. Pick any app and it shows the full footprint, not just the .app bundle.
Take VS Code, which uses 3.01 GB in total. The app bundle is 1.5 GB and Application Support is another 1.51 GB. The caches, the part that's truly regenerable, are only 2.28 MB. A lot of people assume clearing caches frees up gigabytes, and here you can see it doesn't. You get to decide with real numbers.
It also notices when an app is running and tells you to quit it before uninstalling. It's a small detail, but it saves you from a bad afternoon.
Under the hood
For the curious:
- The core is Python 3.9+, installable with
pip install mac-deep-cleaner. - A local web dashboard is served on a loopback port.
- A Swift window shell provides native macOS chrome and full-screen support.
- Scanning is multi-threaded, with content hashing for duplicate detection.
- One tool, three commands:
mac-deep-cleaner,mac-cleaner, andmdc.
What's new in v3.0.5
This release is all about polish, the things you only notice when they're wrong:
- I fixed the missing top inset in browser mode, without disturbing native window and full-screen spacing.
- The dashboard, favicon, README, and macOS icon now all use a single
assets/app_icon.png, and I removed the redundant branding images. - Shared assets now ship in Python distributions and standalone macOS builds.
- The CLI and native bundle versions come from one package version constant, so they can't drift apart.
Installing it
Option 1: Download the app (easiest)
Grab Mac-Deep-Cleaner-macOS.zip (about 9.7 MB) from the v3.0.5 release page.
Unzip it and drag Mac Deep Cleaner.app into your /Applications folder. Each release asset shows a SHA-256 checksum, so you can verify your download:
shasum -a 256 ~/Downloads/Mac-Deep-Cleaner-macOS.zip
The output should match the checksum on the release page.
Option 2: Install with pip
pip install mac-deep-cleaner
mdc
Option 3: Build from source
git clone https://github.com/NK2552003/Mac-Cleaner.git
cd Mac-Cleaner
python3 scripts/build_mac.py
About the macOS warning
The downloadable app isn't notarized by Apple yet, so macOS may tell you it's "damaged" or can't be opened. It isn't damaged. Gatekeeper is just being cautious about a downloaded app that hasn't been notarized.
If you got it from the official release page, move it to /Applications and run:
xattr -d com.apple.quarantine "/Applications/Mac Deep Cleaner.app"
This only removes the download-quarantine flag from that one app. If you'd rather skip Terminal, right-click the app, choose Open, and confirm. Please only do this with builds from the official repo. Notarization is on my to-do list. (The pip install doesn't have this problem.)
What I learned
- Trust is a feature. Showing "Review first: 32.90 GB" instead of a giant green button made the tool feel more useful, not less.
- Boring consistency matters. One icon file, one version constant. Half of v3.0.5 was just deleting duplication.
- Local-first is a relief. No servers, no accounts, and nothing leaves your machine.
Try it, break it, tell me
It's open source under Apache 2.0:
- Download: https://github.com/NK2552003/Mac-Cleaner/releases/tag/v3.0.5
- GitHub: https://github.com/NK2552003/Mac-Cleaner
- PyPI: https://pypi.org/project/mac-deep-cleaner/
If you find an app footprint it misses, or a path it should protect, open an issue. And if it frees up some space for you, a star helps more than you'd think.
So, what's the most surprising thing taking up space on your Mac?
Happing Coding ;)
Top comments (0)