🧹 Mac Cleanup Utility

A lightweight, interactive Python utility designed for developers to reclaim disk space by cleaning up development caches, build artifacts, and system junk.

✨ Features

• Interactive UI: Uses InquirerPy and Rich for a beautiful terminal interface with multi-select checkboxes.

• Smart Scanning: Calculates exactly how much space you'll recover before you delete anything.

• Safe Cleaning: * Keep Root Logic: Optionally clears folder contents without deleting the parent directory (essential for app stability).

• Dry Run by Default: You select exactly what to delete; nothing happens without explicit confirmation.

• Developer Focused: Targets Xcode, Gradle, Flutter, CocoaPods, PNPM, Docker, and more.

• System Utilities: Includes built-in support for Homebrew cleanup and removing unused iOS Simulators.

🐍 Setup with Virtual Environment

To keep your system clean and ensure the script runs with all necessary dependencies, it is recommended to use a Python Virtual Environment.

1. Clone or Download

git clone https://github.com/antocirino/maccleanup

2. Create the Environment

Navigate to the script's folder and run:

cd maccleanup
python3 -m venv venv

3. Activate the Environment

source venv/bin/activate

Once activated, your terminal prompt will usually show (venv).

4. Install Dependencies

pip install -r requirements.txt

5. Run the Script

chmod +x maccleanup.py
./maccleanup.py

6. Deactivate

When you are done, simply run:

deactivate

---

Pro Tip: Create an Alias

If you want to run this cleanup utility from anywhere without manually activating the venv every time, add an alias to your ~/.zshrc (or ~/.bash_profile):

1. Open your config: nano ~/.zshrc
2. Add this line (replace with your actual script path):

alias cleanupmac='/path/to/your/folder/venv/bin/python /path/to/your/folder/maccleanup.py'

3. Save and reload: source ~/.zshrc

Now you can just type maccleanup in any terminal window!

Supported Targets

Category	Included Items
Development	Xcode (DerivedData/Archives), Android Gradle, Flutter Pub, CocoaPods, PNPM, Yarn, Poetry, Pip, Cypress.
Browsers	Google Chrome & Brave Cache.
Apps	Spotify, Slack, Discord.
System	System User Logs, QuickLook Thumbnails, Homebrew, iOS Simulators.

⚠️ Safety Information

This script is a powerful tool. Please keep in mind:

• Caches: Deleting development caches (like Gradle or Pub) is safe, but the next build will be slower as it needs to re-download/re-generate files.
• Archives: Xcode Archives are needed for debugging crashes of older app versions. Delete them only if you no longer need to symbolicate old builds.
• Browser/App Cache: You may be logged out of some services or experience slightly slower loading times immediately after cleaning.

⚙️ Customization

You can easily add new directories to the DIRS_TO_CLEAN list in the script:

{
    "name": "My Custom Folder", 
    "path": "~/Path/To/Folder", 
    "keep_root": True  # Set to True to delete contents only
}

---

📄 License

MIT License. Use it at your own risk!