DiskQuota — User Guide

DiskQuota finds the folders and files that fill up your Mac and shows what you can safely remove. It scans your home folder, the entire disk, or any folder you choose, measures every item by the space it actually occupies on disk, and presents the results as an overview, a folder browser, a list of large files, and a catalog of cleanup candidates such as Xcode build data, package caches, virtual machines, and project build products. Everything you remove goes to the Trash after a confirmation, and Time Machine local snapshots that keep deleted files on disk can be cleared from the same window.

1. Open DiskQuota. On the first launch, a welcome sheet explains Full Disk Access. Grant it now for complete results, or click Continue Without Full Disk Access.
2. Choose what to scan from the folder menu in the toolbar: Home Folder (recommended), Entire Disk (/), or Choose Folder….
3. Click Start Scan or press Command-R. Scanning a home folder usually takes tens of seconds.
4. Read the Overview to see how your startup disk is used and which items are the largest.
5. Open Cleanup Candidates, expand a category, and check the items you want to remove. Select All Safe Items picks everything that is regenerated automatically.
6. Click Move Selected Items to Trash and confirm. Empty the Trash in Finder to reclaim the space.
7. If free space still does not grow, open Local Snapshots and delete the Time Machine snapshots that keep deleted files on disk.

DiskQuota is open source and is distributed as source code on GitHub. It requires macOS 14 Sonoma or later. Building it requires Xcode 16 or later.

1. Clone the repository: git clone https://github.com/RayKitajima/DiskQuota.git
2. Open DiskQuota.xcodeproj in Xcode and run the DiskQuota scheme, or run make run in the repository folder to build a release version and launch it.
3. The release build is created at build/Build/Products/Release/DiskQuota.app. Copy it to your Applications folder before granting Full Disk Access, so the permission belongs to the copy you keep using.

DiskQuota does not use the App Sandbox because it needs to read every folder you ask it to measure. It only reads file sizes and dates. It never uploads or changes your data, and it removes items only when you move them to the Trash yourself.

The DiskQuota window has a sidebar on the left, a toolbar at the top right, and the selected view in the main area.

Sidebar

Volumes lists the startup disk and connected disks with a usage bar, the free space, and the purgeable space. Analysis switches between Overview, Folders, Large Files, Cleanup Candidates, and Local Snapshots. The first four become available after a scan. Local Snapshots is always available. The number next to Cleanup Candidates counts the items you can select, and the number next to Local Snapshots counts the snapshots.

Full Disk Access status

The bottom of the sidebar shows whether Full Disk Access is on. Click it to open the Full Disk Access guide.

Toolbar

The folder button opens the scan target menu. Hold the pointer over it to see the current target. The play button next to it starts a scan. While a scan is running, it becomes a stop button.

Main area

Shows the view selected in the sidebar. Before the first scan, it shows a welcome screen with the current scan target and a Start Scan button.

The welcome sheet appears on the first launch and shows whether Full Disk Access is granted.

macOS protects Mail, Messages, Safari data, Time Machine backups, and parts of the Library folder. Without Full Disk Access, those folders appear as No access and their size is missing from the totals. DiskQuota works without the permission, but the results are more complete with it.

1. Click Open System Settings in the welcome sheet. The Privacy & Security > Full Disk Access list opens.
2. Turn on DiskQuota in the list. If it is not listed, click + and choose DiskQuota, or click Show App in Finder and drag the app into the list.
3. Click Relaunch DiskQuota. macOS applies the permission only to apps launched after it was granted.

The status badge in the sheet updates automatically every few seconds. When it shows Granted, click Get Started.

You can open this guide again at any time with Help > Full Disk Access…, by clicking the Full Disk Access status at the bottom of the sidebar, or with Set Up Full Disk Access… on the welcome screen and in the Overview.

If you start DiskQuota from Terminal or Xcode, macOS applies the permission of that app instead. Grant Full Disk Access to Terminal, or launch DiskQuota from Finder.

Before the first scan, the welcome screen shows the scan target.

Choosing what to scan

• Home Folder (recommended): your personal data, caches, and developer tool data are almost all here, and the scan finishes quickly.
• Entire Disk (/): also measures /Library, /Applications, /private/var, and other system locations. /System/Volumes, /Volumes, /dev, and /Network are skipped.
• Choose Folder…: any folder, such as a projects folder or an external disk.

Starting and stopping

Click Start Scan on the welcome screen or the play button in the toolbar, or choose Scan > Start Scan (Command-R). While scanning, DiskQuota shows the amount found, the number of files and folders, the number of folders it could not read, and the folder being scanned. To stop, click Stop, click the stop button in the toolbar, or press Command-.. The results found so far are shown and marked as partial.

After a scan, cleanup candidates are measured in the background. Click the play button again to scan again with the latest contents.

How sizes are measured

• Sizes are the blocks actually allocated on disk, so sparse files such as Docker.raw, APFS-compressed files, and iCloud files that are not downloaded are measured correctly.
• Files with several hard links are counted once.
• Other volumes, such as external disks inside the scanned folder, are not entered. They appear with an Other volume label.
• Files smaller than 100 KB are grouped into one Other small files row per folder to keep memory usage low.

Startup Disk

The bar splits the startup disk into Used, Purgeable, and Actually free space. When there is purgeable space, a note explains how much free space you would have if macOS released all of it. Manage Local Snapshots opens the Local Snapshots view. See Understanding free space.

Scan Result

Shows the total size, the number of files and folders, the scan duration, and the number of folders that could not be read. When folders could not be read, Set Up Full Disk Access… opens the Full Disk Access guide. When you scan a folder other than the whole disk, DiskQuota also shows roughly how much of the disk is used outside the scan.

Largest Items (Top Level)

A chart of the largest items directly inside the scanned folder. Folders are blue and files are orange. Browse Folders opens the Folders view.

Breakdown by File Kind

Groups files by type, such as video, disk images and virtual machines, ML models, images, archives, documents, and build products.

Cleanup Candidates

Summarizes how much space is safe to remove and how much needs review. Review Cleanup Candidates opens the Cleanup Candidates view.

The Folders view is a tree of everything that was scanned, largest first. The header shows the scanned folder, its total size, and its file count.

• Click the disclosure triangle next to a folder to see what is inside.
• Share of Parent shows how much of the containing folder each item takes up.
• Click a column header (Name, Size, Share of Parent, Files, or Modified) to sort. Click it again to reverse the order.
• Hold the pointer over a row to see the full path, the exact size in bytes, the number of files, and the modification date and time.
• Double-click a row to show it in Finder.
• Right-click selected rows to Show in Finder, Copy Path, or Move to Trash.

A red lock and No access mark folders DiskQuota could not read. See Full Disk Access. Other small files rows group files smaller than 100 KB and cannot be moved to the Trash.

Large Files lists the 300 largest files of 1 MB or more, wherever they are in the scanned folder.

• Click a column header (Name, Size, Kind, Location, or Modified) to sort. The list starts sorted by size.
• Long paths are shortened in the middle. Hold the pointer over the name or location to see the full path. Hold it over the size to see the exact number of bytes.
• Double-click a file to show it in Finder.
• Right-click selected files to Show in Finder, Copy Path, or Move to Trash.

Every category starts collapsed. Its header shows the number of items, how many are safe or need review, and the total size.

Cleanup Candidates collects well-known locations that tend to use a lot of space, plus project build products found during the scan. Candidates are grouped into categories:

Safety levels

An expanded category after Select All Safe Items.

Reading a candidate

• The checkbox selects the item. Items with the Info badge have no checkbox.
• The badges show the safety level. Contents only means DiskQuota empties the folder instead of removing the folder itself. No access means the folder could not be read.
• The path, a description, and, when there is a better way to reclaim the space, a recommended command. Click the copy button next to the command to copy it.
• The size on the right. Finder shows the location in Finder.

Removing candidates

1. Click a category header to expand it, or click Expand All.
2. Check the items you want to remove, or click Select All Safe Items.
3. Check the selection count and total size in the bottom bar.
4. Click Move Selected Items to Trash (Command-Delete) and confirm.
5. Empty the Trash in Finder to reclaim the space.

If you select a folder and an item inside it, the inner item is counted and moved only once. For Docker, Homebrew, simulators, and other tools that manage their own data, the recommended command is usually the better way to reclaim space.

Time Machine takes a snapshot of the startup disk every hour and keeps it for 24 hours. Snapshots keep referencing the blocks of deleted files, so free space in Finder does not grow right after you delete a lot of files. Deleting the snapshots releases that space immediately.

1. Select Local Snapshots in the sidebar. No scan is needed.
2. Select the snapshots to delete, or click Select All. Snapshots older than a day are highlighted in the Age column.
3. Click Delete Selected Snapshots, or click Delete All. You can also right-click selected snapshots and choose Delete….
4. Confirm. If macOS requires administrator privileges, enter your password.

When deletion finishes, DiskQuota shows how much the available space changed. Click Refresh to reload the list and the free-space figures.

Deleted snapshots cannot be restored. Backups on your external Time Machine disk are not affected. macOS does not report the size of individual snapshots, so DiskQuota cannot show them.

• DiskQuota never deletes files permanently. Every removal moves items to the Finder Trash, so you can put them back if you change your mind.
• A confirmation dialog always lists what will be moved and how much space it uses.
• The space is reclaimed only after you empty the Trash in Finder.
• After moving items, DiskQuota updates the scan results and reports how much was moved and anything that could not be moved.

DiskQuota can print a text report without opening a window. Pass --scan with a folder and, optionally, --limit with the number of entries to list (25 by default):

DiskQuota.app/Contents/MacOS/DiskQuota --scan ~ --limit 30

The report lists the largest entries, the largest files, and the cleanup candidates. From the source folder, make cli builds the app and prints a report of your home folder.

DiskQuota is available in English, Japanese, Simplified Chinese, and Traditional Chinese. It follows the language order in System Settings > General > Language & Region. To use a different language for DiskQuota only, add it under Applications in the same settings pane.

Some folders show “No access”

macOS is protecting those folders. Grant Full Disk Access as described in Full Disk Access, then relaunch DiskQuota and scan again.

Full Disk Access is on in System Settings, but DiskQuota shows Off

Quit and relaunch DiskQuota. If you launched it from Terminal or Xcode, grant the permission to that app or launch DiskQuota from Finder. If you rebuilt or moved the app, turn the permission off and on again for the current copy.

macOS asks whether DiskQuota can access my music or other data

While scanning your home folder, DiskQuota reads folders such as your music library, and macOS may ask for permission. DiskQuota only reads file sizes. If you click Don’t Allow, the folder is counted as not accessible and the scan continues.

Free space did not increase after moving items to the Trash

Empty the Trash in Finder. If free space still does not grow, Time Machine local snapshots may still reference the deleted files. Delete them in Local Snapshots.

Deleting snapshots fails

DiskQuota shows the message returned by macOS. Enter an administrator password when asked. If a Time Machine backup is running, wait until it finishes and try again.

A cleanup candidate cannot be selected

Items with the Info badge are shown only to explain the space. Use the app or command in the item’s description. Items with a size of “—” are empty or were already moved to the Trash.

The totals differ from Finder

DiskQuota measures the space each file actually occupies, counts hard-linked files once, and does not enter other volumes. Finder may show the logical file size instead. The Overview also shows roughly how much of the disk is used outside the scanned folder.