mac-cleaner 1.0.0

A safe and intelligent disk cleaning utility for macOS

Mac Cleaner 🧹

English | Español

---

English

A safe and intelligent disk cleaning utility for macOS that helps you reclaim disk space by identifying and removing temporary files, caches, and development artifacts.

Features

• Smart Categorization: Organizes cleanable files into logical categories
• Safety First: Built-in protections prevent deletion of critical system files
• Interactive Selection: Choose exactly what to clean with an easy-to-use CLI
• Dry-Run Mode: Preview what will be deleted before making changes
• Multi-language Support: Automatically detects your system language (English/Spanish)
• Developer-Friendly: Finds and cleans node_modules, Docker data, build caches, and more

What It Cleans

Mac Cleaner safely identifies and removes:

1. Temporary Files: System and application temporary files
2. System Logs: Log files from macOS and applications
3. Homebrew Cache: Downloaded packages and build artifacts
4. Browser Cache: Cache from Safari, Chrome, Firefox, Brave, Edge
5. Node Modules: node_modules directories in your projects
6. User Caches: Application caches (excluding Apple system caches)
7. Development Caches: Xcode, npm, pip, yarn, CocoaPods, Cargo, Gradle
8. Docker Data: Unused Docker images, containers, and volumes

Installation

From PyPI (when published)

pip install mac-cleaner

From Source

# Clone the repository
git clone https://github.com/yourusername/mac-cleaner.git
cd mac-cleaner

# Install in development mode
pip install -e .

# Or install normally
pip install .

Usage

Basic Usage

mac-cleaner

This will:

1. Scan your system for cleanable files
2. Display categories with size information
3. Let you select what to clean
4. Ask for confirmation before deleting

Dry-Run Mode

Preview what will be deleted without making changes:

mac-cleaner --dry-run

Examples

Clean everything:

$ mac-cleaner
Scanning categories...
Categories found:
 1) Temporary Files               2.3 GB (4 items)
 2) System Log Files              856.2 MB (3 items)
 3) Browser Cache                 1.2 GB (5 items)
 4) Node Modules                  4.5 GB (12 items)
 5) Development Cache             3.1 GB (6 items)

Select categories (e.g., 1,3,5 or all):
> all

Clean specific categories:

Select categories (e.g., 1,3,5 or all):
> 3,4,5

Safety Features

Mac Cleaner includes multiple layers of protection:

• ✅ Whitelist approach: Only cleans known safe locations
• ✅ Critical path protection: Prevents deletion of system directories
• ✅ Apple file protection: Skips files starting with com.apple.
• ✅ Permission handling: Gracefully handles permission-denied errors
• ✅ macOS SIP protection: Respects System Integrity Protection
• ✅ User confirmation: Always asks before deleting
• ✅ Dry-run mode: Test before committing to changes

Requirements

• macOS 10.13 or later
• Python 3.8 or later
• Optional: Docker (for Docker cleanup feature)
• Optional: gettext (for translation compilation)

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/mac-cleaner.git
cd mac-cleaner

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black mac_cleaner/

Type Checking

mypy mac_cleaner/

Updating Translations

1. Edit .po files in mac_cleaner/locales/*/LC_MESSAGES/
2. Compile translations:

   python compile_translations.py
   

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

While Mac Cleaner is designed with safety in mind, always ensure you have backups of important data. The authors are not responsible for any data loss.

---

Español

Una utilidad segura e inteligente de limpieza de disco para macOS que te ayuda a recuperar espacio eliminando archivos temporales, cachés y artefactos de desarrollo.

Características

• Categorización Inteligente: Organiza archivos limpiables en categorías lógicas
• Seguridad Primero: Protecciones integradas previenen la eliminación de archivos críticos del sistema
• Selección Interactiva: Elige exactamente qué limpiar con una CLI fácil de usar
• Modo Simulación: Previsualiza qué se eliminará antes de hacer cambios
• Soporte Multi-idioma: Detecta automáticamente el idioma de tu sistema (Inglés/Español)
• Amigable para Desarrolladores: Encuentra y limpia node_modules, datos de Docker, cachés de compilación, y más

Qué Limpia

Mac Cleaner identifica y elimina de forma segura:

1. Archivos Temporales: Archivos temporales del sistema y aplicaciones
2. Logs del Sistema: Archivos de log de macOS y aplicaciones
3. Caché de Homebrew: Paquetes descargados y artefactos de compilación
4. Caché de Navegadores: Caché de Safari, Chrome, Firefox, Brave, Edge
5. Node Modules: Directorios node_modules en tus proyectos
6. Cachés de Usuario: Cachés de aplicaciones (excluyendo cachés del sistema de Apple)
7. Cachés de Desarrollo: Xcode, npm, pip, yarn, CocoaPods, Cargo, Gradle
8. Datos de Docker: Imágenes, contenedores y volúmenes de Docker no usados

Instalación

Desde PyPI (cuando se publique)

pip install mac-cleaner

Desde el Código Fuente

# Clonar el repositorio
git clone https://github.com/yourusername/mac-cleaner.git
cd mac-cleaner

# Instalar en modo desarrollo
pip install -e .

# O instalar normalmente
pip install .

Uso

Uso Básico

mac-cleaner

Esto:

1. Escanea tu sistema buscando archivos limpiables
2. Muestra categorías con información de tamaño
3. Te permite seleccionar qué limpiar
4. Pide confirmación antes de eliminar

Modo Simulación

Previsualiza qué se eliminará sin hacer cambios:

mac-cleaner --dry-run

Ejemplos

Limpiar todo:

$ mac-cleaner
Escaneando categorías...
Categorías encontradas:
 1) Archivos Temporales          2.3 GB (4 items)
 2) Archivos de Log del Sistema  856.2 MB (3 items)
 3) Caché de Navegadores         1.2 GB (5 items)
 4) Node Modules                 4.5 GB (12 items)
 5) Caché de Desarrollo          3.1 GB (6 items)

Selecciona categorías (ej: 1,3,5 o all):
> all

Limpiar categorías específicas:

Selecciona categorías (ej: 1,3,5 o all):
> 3,4,5

Características de Seguridad

Mac Cleaner incluye múltiples capas de protección:

• ✅ Enfoque de lista blanca: Solo limpia ubicaciones conocidas y seguras
• ✅ Protección de rutas críticas: Previene la eliminación de directorios del sistema
• ✅ Protección de archivos Apple: Omite archivos que comienzan con com.apple.
• ✅ Manejo de permisos: Maneja errores de permisos denegados de forma elegante
• ✅ Protección SIP de macOS: Respeta la Protección de Integridad del Sistema
• ✅ Confirmación del usuario: Siempre pide confirmación antes de eliminar
• ✅ Modo simulación: Prueba antes de comprometerte con los cambios

Requisitos

• macOS 10.13 o posterior
• Python 3.8 o posterior
• Opcional: Docker (para la función de limpieza de Docker)
• Opcional: gettext (para compilar traducciones)

Desarrollo

Configurar Entorno de Desarrollo

# Clonar el repositorio
git clone https://github.com/yourusername/mac-cleaner.git
cd mac-cleaner

# Instalar con dependencias de desarrollo
pip install -e ".[dev]"

Ejecutar Tests

pytest

Formateo de Código

black mac_cleaner/

Verificación de Tipos

mypy mac_cleaner/

Actualizar Traducciones

1. Edita los archivos .po en mac_cleaner/locales/*/LC_MESSAGES/
2. Compila las traducciones:

   python compile_translations.py
   

Contribuir

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Descargo de Responsabilidad

Aunque Mac Cleaner está diseñado pensando en la seguridad, asegúrate siempre de tener copias de seguridad de datos importantes. Los autores no son responsables de ninguna pérdida de datos.