# Your Startup Disk Is Almost Full: Find Where the Space Went

> The alert is about working headroom, not about deleting files. Measure with df and diskutil, check local snapshots first, then make one structural change instead of many small deletions.

Published: 2026-08-09 | Updated: 2026-08-16

The alert arrives at the worst moment: you are exporting a video, installing an update,
or saving a document, and macOS interrupts with **Your startup disk is almost full**.
The reflex is to open Downloads and start deleting. That usually frees a few gigabytes,
the alert comes back within a day, and nothing has been learned.

macOS is reporting that the volume has run out of the working headroom it needs for swap,
updates, and temporary files. Space that is reclaimable but still pinned counts against
you exactly like a real file, so deleting visible files sometimes moves the number and
sometimes does nothing at all.

**Short answer:** find out where the space went before deleting anything. Check free
space with `df -h /`, look at **System Settings > General > Storage**, and if the number
barely moves after you delete a large file, the space is pinned by snapshots or purgeable
pools rather than by the files you can see.

## What the alert actually means

macOS keeps a reserve on the startup volume. It is used for virtual memory swap,
installer staging during a system update, temporary files apps write while working, and
APFS bookkeeping. When free space falls toward that reserve, the system warns you.

Apple does not publish the exact trigger threshold, and it varies with the size of the
volume and what the system is doing at that moment. Treat the alert as a signal about
headroom, not as a precise measurement you can reason backwards from.

Two consequences matter more than the number:

- A Mac low on disk space gets slow before it gets broken. Swap has nowhere to go, so
  memory pressure rises and the system starts compressing and paging aggressively.
- A macOS update can refuse to install even when the installer looks smaller than your
  free space, because it stages a full copy before applying it.

## Measure before you delete

Start with the file system rather than with Finder, because Finder reports space in a
way that already folds in reclaimable pools.

```
df -h /
```

On a Mac with a 1 TB drive that reads something like this:

```
Filesystem        Size    Used   Avail Capacity   Mounted on
/dev/disk3s1s1   926Gi    12Gi   299Gi     4%     /
```

The `Used` column is small because `/` is the sealed system snapshot, not your data
volume. `Size` reads 926Gi against a drive sold as 1 TB because `df` counts in binary
gibibytes and Apple counts in decimal gigabytes. Nothing is missing; the same bytes are
being described in two units.

For the container as a whole, ask `diskutil` instead:

```
diskutil info / | grep -i "Container"
```

```
   Container Total Space:     994.6 GB (994610155520 Bytes)
   Container Free Space:      321.0 GB (321045377024 Bytes)
```

Now you have a real baseline. Write the free-space number down. Every step below is
judged by whether that number moves.

## Where the space usually is

A full startup disk on a personal Mac is almost always one of six things. Work down this
list rather than deleting whatever is largest.

| Suspect | How to confirm | Where it goes |
|---|---|---|
| Local Time Machine snapshots | `tmutil listlocalsnapshots /` returns entries | [Delete local snapshots](https://mole.fit/blog/how-to-delete-local-time-machine-snapshots-mac) |
| Photos library | It is usually the largest single item in Home | [Free up Photos storage](https://mole.fit/blog/how-to-free-up-photos-storage-mac) |
| iOS device backups | `~/Library/Application Support/MobileSync/Backup` | [Delete old iPhone backups](https://mole.fit/blog/how-to-delete-iphone-backups-mac) |
| Mail downloads | Mail's account data grows without bound | [Reduce Mail storage](https://mole.fit/blog/how-to-reduce-mail-storage-mac) |
| Developer caches | Xcode, Docker, Homebrew, node package stores | [Clear dev caches](https://mole.fit/blog/how-to-clear-dev-caches-mac) |
| Large forgotten files | Old exports, disk images, downloads | [Find large files](https://mole.fit/blog/how-to-find-large-files-on-mac) |

macOS folds several of these into the **System Data** category in Storage settings, which
is what makes that bar look alarming and unexplained. It names a leftover, not a folder
you can open; see [what System Data actually contains](https://mole.fit/blog/what-is-system-data-on-mac).

## When deleting does not free space

This is the case that sends people to a cleaner. You delete a 20 GB file, empty the
Trash, and free space moves by almost nothing.

The usual cause is APFS copy-on-write. A local Time Machine snapshot still references
the blocks the deleted file occupied, so the file system cannot release them. The space
shows up as purgeable rather than free. Check it directly:

```
tmutil listlocalsnapshots /
```

If that returns entries, read the [snapshot guide](https://mole.fit/blog/how-to-delete-local-time-machine-snapshots-mac)
before doing anything else. Thinning snapshots is often the entire fix, and it does not
touch the backups on your external Time Machine disk.

The second cause is that macOS considers some space reclaimable and is therefore in no
hurry to reclaim it. It will free that space when something actually needs it. This is
also why a Mac can report very little free space and still install an update
successfully.

## Use Storage settings for what it is good at

**System Settings > General > Storage** is useful for two things: the category bar gives
you a rough shape of the volume, and the recommendations panel exposes controls you would
otherwise have to hunt for, including emptying the Trash automatically and reviewing
large files.

It is less useful as a measurement. The categories overlap, the numbers settle slowly
after a change, and System Data absorbs anything the classifier is unsure about. Use it
to navigate, use `df` and `diskutil` to measure.

## What not to do

- **Do not delete files from `/System`, `/Library`, or `/private` to make room.** The
  system volume is sealed and read-only on modern macOS, and the parts that are writable
  are load-bearing.
- **Do not empty caches on a schedule.** Regenerable caches come straight back and the
  first run of every app after the sweep is slower. See
  [what is safe to clear](https://mole.fit/blog/how-to-clear-cache-on-mac).
- **Do not trust a tool that promises to free a specific amount of purgeable space.**
  Purgeable is an upper bound over mixed pools, not an inventory.
- **Do not delete a Photos library, Mail data, or a backup folder in Finder** to reclaim
  space. Use the owning app so its database stays consistent.

## Get to a stable state, not a big number

Aim for headroom you keep rather than the largest one-off number. A Mac sitting
comfortably above its reserve stops warning you and stops paging under load.

Getting there usually takes one structural change rather than many small deletions:
moving a Photos library or a video archive to an external disk, turning on Optimize Mac
Storage for a large library, or removing a development toolchain you no longer use. Any
one of those outlasts an afternoon of deleting screenshots.

## Where a review tool fits

[Mole](https://mole.fit/) measures before it offers to delete. It maps the volume by real on-disk size,
shows what each candidate is before anything is removed, and moves items to the Trash
instead of deleting them outright, so a wrong call is recoverable. It will not promise
you a purgeable number it cannot prove.

## Order of operations

1. Record free space with `df -h /` and `diskutil info /`.
2. Check `tmutil listlocalsnapshots /` and handle snapshots first if any exist.
3. Find the largest real consumers, in Home before anywhere else.
4. Make one structural change, then re-measure.
5. Stop when the volume has headroom, not when a tool reports a satisfying total.

## FAQ

### Why does the alert come back the day after I delete files?

Because the deletions did not change the structure. If a Photos library, an iOS backup,
or a snapshot set is the real occupant, deleting a few gigabytes of documents leaves you
just above the threshold and the next update or swap burst puts you back under it.

### How much free space should a Mac have?

There is no official figure, and any specific percentage you read is someone's rule of
thumb rather than an Apple specification. Practically: enough for a full macOS update to
stage, plus room for swap under your normal workload.

### Does the alert mean the drive is failing?

No. It reports capacity, and says nothing about the health of the drive. That is a
separate question with separate symptoms.

### Can I ignore it?

For a while, yes, and macOS will keep working by reclaiming purgeable space. You pay for
it in a Mac that slows down under memory pressure and updates that start failing, so
fixing it beats dismissing it every day.

---

Canonical HTML page: https://mole.fit/blog/mac-startup-disk-full
Blog index for agents: https://mole.fit/blog/llms.txt
Site index for agents: https://mole.fit/llms.txt