# How to Clean Installer Files with Mole: A Complete Guide

> Easily clean installer files on macOS with Mole. Discover how the mo clean command safely removes old installer apps and data using a deep system scan. Learn more today.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: how-to-guide
- Published: 2026-03-20

---

**To clean installer files with Mole, run `mo clean` which triggers the `clean_deep_system` function in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh) to scan for macOS installer apps and data folders older than 14 days, safely removing them with `safe_sudo_remove` while respecting active processes and whitelist protections.**

Mole is an open-source macOS cleanup utility maintained by **tw93/Mole** that automates the removal of system debris, including stale macOS installer applications. This guide explains exactly how Mole identifies and cleans installer files, where the logic resides in the source code, and how to execute dry-runs or configure protections.

## How Mole Cleans macOS Installer Files

When you execute `mo clean`, the command invokes [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh), which acts as the main driver. This script initializes a sudo session via [`lib/core/sudo.sh`](https://github.com/tw93/Mole/blob/main/lib/core/sudo.sh) and then delegates to [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh) to perform deep system cleaning.

Inside [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh), the `clean_deep_system` function orchestrates the scan. For installer files specifically, it executes two distinct detection passes:

1. **Install Data Folders**: Checks for `/macOS Install Data` directories at the root level.
2. **Installer Applications**: Enumerates bundles matching `/Applications/Install macOS*.app`.

### The Detection Logic in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh)

The source code at lines 97–149 of [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh) contains the specific logic for targeting installer artifacts.

For the data folder, the script uses a 14-day threshold. If the directory exists and its modification time exceeds 14 days, `safe_sudo_remove` is invoked:

```bash

# lib/clean/system.sh (lines 97-113)

if [[ -d "/macOS Install Data" ]]; then
  # Check if older than 14 days

  if [[ $(find "/macOS Install Data" -mtime +14) ]]; then
    safe_sudo_remove "/macOS Install Data"
  fi
fi

```

For installer applications, the loop at lines 121–148 iterates through matching app bundles, skipping any processes currently running via `pgrep -f "$installer_app"`:

```bash

# lib/clean/system.sh (lines 121-148)

for installer_app in /Applications/Install\ macOS*.app; do
  # Skip if installer is currently running

  if pgrep -f "$installer_app" > /dev/null; then
    continue
  fi
  
  # Check age and calculate size

  if [[ $(find "$installer_app" -mtime +14) ]]; then
    size_kb=$(get_path_size_kb "$installer_app")
    safe_sudo_remove "$installer_app"
  fi
done

```

### Safety Mechanisms: Process Checks and Whitelists

Mole implements two critical safeguards to prevent accidental deletion of active or protected installer files.

**Process Detection**: Before removing any installer application, the script executes `pgrep -f "$installer_app"` to verify the installer is not currently executing. If the process exists, the cleanup skips that bundle entirely.

**Whitelist Protection**: All removal operations route through `safe_sudo_remove` defined in [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh). This function consults the user whitelist (managed via [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh)) prior to executing `sudo rm -rf`. Any path added to `~/.config/mole/whitelist` is permanently excluded from cleanup operations.

## Step-by-Step: Clean Installer Files with Mole

Use these commands to safely identify and remove stale macOS installer artifacts.

### 1. Preview What Would Be Removed

Execute a dry-run to see which installer files Mole would delete without actually removing them:

```bash
mo clean --dry-run | grep -i "installer"

```

This parses the output to show only lines related to installer apps or data folders.

### 2. Perform the Cleanup

Run the standard clean command to remove installer files older than 14 days:

```bash
mo clean

```

Mole will request your administrator password on the first run to establish a cached sudo session via [`lib/core/sudo.sh`](https://github.com/tw93/Mole/blob/main/lib/core/sudo.sh). The system cleanup module then executes `clean_deep_system` to process installer files.

### 3. Automate in Non-Interactive Environments

For CI pipelines or remote scripts, run system cleanup without prompts:

```bash
mo clean --non-interactive --system-only

```

The `--system-only` flag ensures Mole targets system-level debris including installer data folders, while `--non-interactive` suppresses the TUI spinner and confirmation prompts.

### 4. Protect Specific Installers from Deletion

To prevent Mole from removing a specific macOS installer, add its path to the whitelist:

```bash
echo "/Applications/Install macOS Ventura.app" >> ~/.config/mole/whitelist
mo clean

```

The `safe_sudo_remove` function in [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh) will now skip this bundle during the age-check loop in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh).

## Key Source Files and Functions

Understanding the source structure helps you customize or debug the installer cleanup behavior.

- **[`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh)**: Main driver that parses CLI flags (`--dry-run`, `--system-only`), initializes the sudo session, and invokes `perform_cleanup`.
- **[`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh)**: Contains `clean_deep_system` function. Lines 97–113 handle `/macOS Install Data` folders; lines 121–148 process `Install macOS*.app` bundles with process detection and size calculation.
- **[`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh)**: Defines `safe_sudo_remove` (whitelist checking and safe deletion) and `get_path_size_kb` (disk usage calculation).
- **[`lib/core/sudo.sh`](https://github.com/tw93/Mole/blob/main/lib/core/sudo.sh)**: Manages cached sudo credentials and session cleanup. Used by [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) before executing system-level removals.
- **[`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh)**: Management interface for the whitelist file at `~/.config/mole/whitelist`.

## Summary

- Mole cleans installer files through the `clean_deep_system` function in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh), triggered by the `mo clean` command.
- The script targets `/macOS Install Data` folders and `/Applications/Install macOS*.app` bundles older than 14 days.
- **Process safety** is enforced via `pgrep` checks to ensure running installers are never deleted.
- **Whitelist protection** routes all deletions through `safe_sudo_remove` in [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh), respecting user-defined exclusions.
- Use `--dry-run` to preview deletions and `--non-interactive` for automated scripting.

## Frequently Asked Questions

### Will Mole delete a macOS installer that I'm currently running?

No. The cleanup logic in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh) explicitly checks for active processes using `pgrep -f "$installer_app"` before removal. If the installer application is currently executing, Mole skips that bundle and leaves it untouched.

### How do I prevent Mole from deleting a specific installer?

Add the full path to the installer application to your whitelist file. Execute `echo "/Applications/Install macOS [Version].app" >> ~/.config/mole/whitelist` before running `mo clean`. The `safe_sudo_remove` function in [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh) checks this whitelist prior to executing any deletion.

### What happens if the installer files are less than 14 days old?

Mole preserves installer files that are newer than 14 days. Both the `/macOS Install Data` folder check (lines 97–113) and the application bundle loop (lines 121–148) in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh) use `find` with `-mtime +14` to enforce this retention period.

### Is it safe to run `mo clean` on a system without backups?

While Mole implements safeguards like process detection and whitelists, any system-level cleanup tool carries inherent risk. The `safe_sudo_remove` function in [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh) uses `sudo rm -rf` for final deletion, which is irreversible. It is recommended to run `mo clean --dry-run` first to review targets, maintain Time Machine or other backups, and verify your whitelist configuration before executing live cleanup operations.