Self-hosted service
mac-cleanup/mac-cleanup-py avatar
mac-cleanup/mac-cleanup-py

mac-cleanup-py: a terminal cleanup script for macOS with 40 modules

👨‍💻 Python cleanup script for macOS

2,373 stars100 forksPythonApache-2.0

At a glance

What is it?
mac-cleanup-py is an Apache-2.0 Python rewrite of mac-cleanup-sh that clears caches, logs and Trash from the command line. It is a good fit for developers with a lot of toolchain caches and a poor fit for anyone who wants a graphical, reversible cleaner.
Who is it for?
Adopt mac-cleanup-py if you work on macOS in a terminal and want one command that sweeps developer caches from Homebrew, npm, pnpm, yarn, Go, Gradle, CocoaPods, Xcode and Docker. Do not adopt it if you need a preview of every file before deletion, a graphical interface, or a rollback path; the README documents --dry-run and --verbose but no undo.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 23 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mac-cleanup/mac-cleanup-py2,373 ★ · -1
Star history
Repository2026-09-302026-11-21
mac-cleanup/mac-cleanup-py2.4k2.4k

-1 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What mac-cleanup-py removes that a manual rm does not

The README frames the project as a rewrite of mac-cleanup-sh in Python, and the feature list is short: empty Trash, delete unnecessary logs and files, clear cache. The detail sits in the default module list, which names around forty tools. Some are generic (system_caches, system_log, trash, dns_cache, inactive_memory). The rest are application-specific: adobe, android, arc, brew, bun, cacher, chrome, chromium, composer, conan, docker, dropbox, ea, gem, go, google_drive, gradle, ios_apps, ios_backups, java_cache, jetbrains, kite, lunarclient, minecraft, microsoft_teams, npm, obsidian, nuget, pnpm, pod, poetry, pyenv, steam, telegram, wget_logs, xcode, xcode_simulators, yarn.

That list is the product. A developer running Xcode, CocoaPods, npm and Docker accumulates derived data and package caches in paths that are not obvious and are not all under one directory. Writing that list yourself is possible, but it drifts as tools change their layout. The intended user is a macOS developer who is comfortable in a shell and wants a repeatable sweep rather than a one-off rm. If you only ever clear the Trash and browser cache, the module list is mostly dead weight.

How the module system works and where custom modules live

The repository layout shows a mac_cleanup package plus a module_template.py at the top level. The template file is the strongest signal about the architecture: modules are meant to be authored individually and dropped in, rather than all logic living in one script. The CLI exposes -p / --custom-path, described in the help output as "Specify path for custom modules", so a user can point the tool at a directory of their own module files instead of relying only on the built-in set.

The help output also lists -c / --configure, described as "Open module configuration screen". Combined with the inquirer and toml dependencies in pyproject.toml, the picture is a terminal UI that lets you select which modules run, with configuration persisted to a file. The README does not spell out where that configuration file is written, which is a gap worth knowing about before you rely on it: you can select modules interactively, but the documentation does not tell you how to inspect or version the resulting config.

The runtime dependencies are worth reading as a statement of intent. rich handles terminal output, inquirer drives prompts, attrs and beartype are used for typed data structures and runtime type checks, toml handles configuration, and xattr is listed, which suggests the tool touches extended attributes on files it deletes. That last one is the detail that separates this from a shell script doing rm -rf: extended attributes are used by macOS for quarantine flags and other metadata, and clearing them has consequences beyond freeing space.

Installing mac-cleanup-py and a first run

The README gives two install paths. Homebrew is the first:

bash
brew install mac-cleanup-py

The pip path installs the package under its PyPI name, mac-cleanup, which differs from the repository name:

bash
pip3 install mac-cleanup

Note the naming split. The Homebrew formula is mac-cleanup-py, the PyPI distribution is mac-cleanup, and the installed command is mac-cleanup. The pyproject.toml confirms the console script mapping with mac-cleanup = "mac_cleanup:main". Getting this wrong is the most likely first-run failure: pip3 install mac-cleanup-py will not resolve, because the README names mac-cleanup as the PyPI project.

Before deleting anything, use the dry run flag. The help output describes -n / --dry-run as "Run without deleting stuff":

bash
mac-cleanup -n

What you should see is the same flow the real run would take, minus the deletions. To see the folders involved, add verbose output, described in the help as "Print folders to be deleted":

bash
mac-cleanup -v

If you want to choose modules rather than run the full default set, open the configuration screen:

bash
mac-cleanup -c

The help output also lists -f / --force, "Accept all warnings", and -u / --update, "Update Homebrew on cleanup". The -u flag is worth pausing on: it means a cleanup run can also trigger a Homebrew update, which is a much larger and slower operation than clearing a cache directory.

The dry run is a preview, not a rollback

The README documents -n / --dry-run as running "without deleting stuff" and -v / --verbose as printing the folders to be deleted. It does not document an undo, a quarantine area, or a restore command. Deletion is deletion. For cache directories that is usually acceptable, because the tools regenerate them on next use. For the modules that are not caches, it is not.

Three modules in the default list deserve scrutiny. ios_backups is described as removing iOS device backups, and those are not regenerable from the Mac: if the only copy of a device backup is on this machine, deleting it is permanent. trash is described as emptying the Trash on all mounted volumes and the main HDD, which includes external drives you may have mounted at the time. system_log and system_caches reach into system-level locations rather than user-level application caches.

The --force flag makes this sharper. It is described as "Accept all warnings", so a run with -f suppresses the prompts that would otherwise stop you before a destructive step. Combining -f with a module set that includes ios_backups or trash is the configuration most likely to cost someone data. A dry run first is not optional advice here; it is the only preview mechanism the project documents.

Where mac-cleanup-py is the wrong tool

This is a CLI utility for people who know what a cache directory is. It is not a disk-space analyser. If your problem is that you do not know what is consuming 200 GB, mac-cleanup-py will not tell you: it deletes from a fixed list of known locations, and it does not rank or visualise usage. Reach for a disk usage tool first, then use this to clear what you identified.

It is also a poor fit for shared or managed machines. The default modules include system_log and system_caches, and the trash module operates on all mounted volumes. On a work laptop with an MDM profile, or a machine where other people rely on logs for support, the module set is broader than you want. The --configure screen exists precisely so you can narrow it, but the README does not document which modules are enabled by default, so you have to open the screen to find out.

Finally, it is a macOS-only tool by construction. The classifiers in pyproject.toml list Operating System :: MacOS, and the module list is entirely macOS applications and paths. There is no Linux or Windows story, and the PyPI name does not imply portability.

mac-cleanup-py against a general-purpose cleaner

The obvious comparison is with a graphical macOS cleaner that scans the disk and presents categories with checkboxes. The difference in approach is the direction of the decision. A scanner-based cleaner looks at what is on your disk and asks you to approve items it found. mac-cleanup-py does the opposite: it ships a fixed list of known cache and log locations, and you approve or exclude modules before it runs.

That inverts the failure mode. A scanner can surprise you with an item you did not expect to see and let you deselect it. mac-cleanup-py can delete something you did not think about, because the module was in the default set and you did not open --configure. In exchange, mac-cleanup-py is scriptable and repeatable: the same command produces the same sweep on every machine, which a graphical scanner generally does not offer. For a developer who wants a cleanup step in a periodic routine, the fixed-list model is the more useful one. For someone who wants to see and judge each item, it is the wrong shape entirely.

The other comparison is with the original mac-cleanup-sh, which the README names as the project this one rewrites. Same idea, different implementation language. The Python version pulls in rich, inquirer, attrs, beartype and toml as runtime dependencies, which is a heavier footprint than a shell script but buys the interactive configuration screen and typed module definitions. If you want zero dependencies and do not need the config UI, the shell original is the lighter choice.

Maintenance, licence and what to check before adopting

The repository is not archived. The last push was on 2026-04-14. The most recent release listed is v3.3.0 from 2025-03-19, following v3.2.0 on 2025-03-01 and v3.1.2 on 2024-10-13. The version in pyproject.toml matches v3.3.0, and the help output prints Version: 3.3.0, so the released artefact and the repository are in step.

The upgrade cost is low on the surface. Homebrew and pip both handle it, and the CLI surface is five flags plus the help flag, so there is little to relearn between versions. The real cost is in the module list. Every module encodes assumptions about where a third-party application keeps its cache, and those paths change when the application updates. A module that silently stops matching anything does not fail loudly; it just stops freeing space. That is the maintenance burden you inherit, whether or not you contribute upstream.

On licensing: the project is Apache-2.0, stated in the README and in the license field of pyproject.toml. Apache-2.0 is a permissive licence that includes an explicit patent grant and requires preservation of notices. If you fork it or vendor the modules into an internal tool, keep the LICENSE file and attribution. That is a description of the licence text, not legal advice; if you are redistributing it inside a commercial product, have your own counsel read the terms.

Before adopting, verify three things on your own machine: which modules are actually enabled after mac-cleanup -c, whether ios_backups and trash are in that set, and what mac-cleanup -v prints on a dry run. The README does not answer the first two.

Editorial conclusion

Adopt mac-cleanup-py if you work on macOS in a terminal and want one command that sweeps developer caches from Homebrew, npm, pnpm, yarn, Go, Gradle, CocoaPods, Xcode and Docker. Do not adopt it if you need a preview of every file before deletion, a graphical interface, or a rollback path; the README documents --dry-run and --verbose but no undo. Before running it on a machine you care about, install it, run mac-cleanup -n to see the flow without deletion, then mac-cleanup -v to print the folders it would remove, and check the default module list against the tools you actually have installed.

Frequently asked questions

Is mac-cleanup-py safe to run?

The project documents a dry run flag, -n or --dry-run, described as running without deleting stuff, and -v or --verbose, which prints the folders to be deleted. It does not document an undo or restore path, and the default module list includes ios_backups and trash, so previewing before a real run matters.

What is the best cleanup tool for a Mac?

The README does not compare mac-cleanup-py with other cleaners, so there is no ranking to quote from it. What it does state is the shape of this tool: a terminal script with roughly forty default modules covering developer caches, application caches and system locations, installed through Homebrew or pip.

How can I clear system data on my Mac in 2026?

mac-cleanup-py ships modules named system_caches, system_log, dns_cache and inactive_memory, and the README describes the tool as clearing cache, logs and Trash. Run mac-cleanup -n first, then mac-cleanup -v, to see which folders a run would touch before you let it delete.

What is cleanup_installer on my Mac?

The README does not mention cleanup_installer. It documents mac-cleanup-py as installed through brew install mac-cleanup-py or pip3 install mac-cleanup, with the mac-cleanup command and a -c / --configure screen.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. mac-cleanup/mac-cleanup-py on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mac-cleanup-mac-cleanup-py.svg)](https://hysenlabs.com/projects/mac-cleanup-mac-cleanup-py)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mac-cleanup-mac-cleanup-py.svg)](https://hysenlabs.com/projects/mac-cleanup-mac-cleanup-py)

Was this useful?