Documentation

Use Expunge with confidence.

Install the app, review an application’s related files, and remove only the items you choose. Use the command-line tool when you want to inspect or automate the same workflow.

01 · Get the app

Installation

Expunge runs on macOS 13 or later. Get the latest available installer from the download page. Open the downloaded disk image, then drag Expunge.app to its Applications shortcut.

Open Expunge from Applications.
If macOS asks whether to open an app downloaded from the internet, review the prompt and confirm that you want to open Expunge.
For broader related-file scans, grant Expunge Full Disk Access in System Settings → Privacy & Security → Full Disk Access, then restart the app so the permission takes effect.

02 · First run

Getting started

Choose a library. Select User or System above the app browser.
Find an app. Search by app name or bundle identifier, sort by name, and choose grid or list view.
Inspect its footprint. Select an app to load related files in the detail pane. Expunge groups paths by category and selects suggested items for removal.
Choose what to remove. Review the paths and policy hints. Change individual checkboxes, select or clear everything, or adjust a whole category.
Review before removing. Choose Expunge to see the removal preview. Confirm to move the selected items to macOS Trash.

Items are moved to Trash so you can recover them until you empty it. Expunge does not permanently delete the selected files during this workflow.

03 · Explore the interface

The app window

The main window has an app browser on the left and a related-files detail pane on the right. Drag the divider between them to resize the browser.

App browser

Switch between User and System apps, search by name or bundle identifier, sort names in either direction, and choose grid or list view. In grid view, adjust icon size at the bottom of the pane.

Related files

Choose an app to inspect the discovered paths. Expand or collapse categories, review policy hints, and select paths individually or in groups. The Expunge button opens a preview before anything moves to Trash.

Toolbar and settings

The toolbar opens Settings and the local Expunge log, changes the interface language, and switches between light and dark appearance. Settings also shows the command-line tool’s install status and lets you install or remove its command link.

Protected apps

Some system or Apple apps are restricted by policy. Expunge marks these in the interface and may require an additional confirmation before removal; apps blocked by policy cannot be expunged.

04 · Terminal

Command-line interface

The expunge command is included with the app. On first launch, you may be offered the option to install it. You can also install it any time in Settings → Command-line tool. Then open Terminal and check the available commands:

expunge --help

Scan installed apps

With no subcommand, Expunge runs a user-app scan. The text output is tab-separated; add --json for machine-readable output.

expunge scan
expunge scan --partition system
expunge scan --partition all --json

Find related files

related takes a path to an app bundle, not its display name. Its JSON output can be saved as a manifest for review or use with purge.

expunge related "/Applications/Some App.app" --json > manifest.json

Preview and move items to Trash

purge is a dry run unless you pass --yes. Inspect the proposed paths first; add --yes only when you want to move them to Trash.

expunge purge --manifest manifest.json
expunge purge --manifest manifest.json --yes

When a manifest contains a restricted system app, the confirmed command also requires --acknowledge-system-risk.

Check permissions and local state

Run doctor to check scan permissions, rules, Trash access, and the local Expunge log. It reports missing permissions and returns a non-zero status when attention is needed.

expunge doctor

Rules directory

scan, related, and purge accept --rules <directory> to load an override.json directory for that command.

Need help? Contact us.