The macOS Tahoe not enough storage error is one of the most common reasons an upgrade stalls. You click "Update Now," the installer downloads successfully, and then a dialog stops you cold: "macOS Tahoe cannot be installed because your disk does not have enough free space." The frustrating part is that macOS doesn't always tell you how much space it actually needs. This guide explains exactly what the updater requires, which files are genuinely safe to delete, and how to clear just enough headroom to let the installation proceed.
Why Does the Tahoe Installer Need So Much Space?
macOS upgrades are not simple file replacements. The installer stages a full copy of the OS to a temporary location on your disk, applies the update, then cleans up. For macOS Tahoe, Apple's software update mechanism typically requires:
- ~13–15 GB for the installer bundle itself (already downloaded to
/Applications/Install macOS Tahoe.appor staged internally by Software Update) - ~20–25 GB of working space during the installation phase for the APFS snapshot, delta patches, and recovery partition update
- A practical minimum of ~25–30 GB free before you start, to give the installer comfortable headroom
APFS's "purgeable" space complicates the picture. macOS reports purgeable space as available in Finder, but the installer may not fully reclaim it before it checks free space. That is why your disk can show "18 GB available" yet still throw an error — the installer wants hard free space, not optimistic purgeable capacity.
Check Your Actual Free Space First
Open Terminal and run:
df -h /Look at the Avail column. This is what the installer actually sees. If it is below 25 GB, you need to clear room before proceeding. For a more detailed breakdown, System Information → Storage (or Apple menu → About This Mac → More Info → Storage) shows the category breakdown macOS uses internally.
The macOS Tahoe Installation Needs More Space: What to Target
Before deleting anything, understand the risk level of each category. Some deletions are completely safe; others require care.
| Category | Typical Size | Safe to Delete? | Notes |
|---|---|---|---|
User cache files (~/Library/Caches) |
1–8 GB | Generally yes | Apps rebuild caches on next launch; some apps may be slower temporarily |
System cache files (/Library/Caches) |
0.5–3 GB | Yes, with care | Requires admin password; macOS rebuilds on demand |
iOS/iPadOS device backups (~/Library/Application Support/MobileSync/Backup) |
5–50+ GB | Yes, if backed up to iCloud | Verify iCloud backup is current before deleting local backups |
Xcode derived data (~/Library/Developer/Xcode/DerivedData) |
5–30 GB | Yes | Xcode rebuilds automatically; next build takes longer |
Xcode simulator runtimes (~/Library/Developer/CoreSimulator/Profiles/Runtimes) |
5–15 GB each | Yes, if not needed | Re-download from Xcode → Settings → Platforms |
Old iOS/macOS update files (/Library/Updates) |
1–8 GB | Yes | Stale update caches; safe to remove |
| Trash | Varies | Yes, once confirmed | Empty Trash before anything else — easy wins |
| Downloads folder | Varies | Review individually | Move to external drive or cloud before deleting |
Mail attachments (~/Library/Mail) |
1–10 GB | Caution | Mail may re-download from server, but verify first |
| System files / app bundles | — | No (without research) | Do not delete files you cannot identify |
Step-by-Step: Free Space for the Tahoe Update
Step 1 — Empty the Trash and remove obvious clutter
- Right-click the Trash icon in the Dock → Empty Trash. This is always the first step and is completely safe.
- Open your Downloads folder and move large files you still need to an external drive or delete items you no longer need.
Step 2 — Clear user caches with Terminal
- Quit all open applications first.
- Open Terminal and run:
This deletes all per-user cache files. Apps will rebuild caches on next launch. Some apps (notably browsers) may log you out of cached sessions.rm -rf ~/Library/Caches/* - Check how much you recovered:
df -h /
Step 3 — Remove Xcode derived data (if you use Xcode)
- In Terminal:
rm -rf ~/Library/Developer/Xcode/DerivedData - If you have simulator runtimes you no longer need, open Xcode → Settings → Platforms, select old runtimes, and click the minus button to remove them from within Xcode rather than deleting files manually.
Step 4 — Check for stale iOS device backups
- Open Finder → your connected iPhone (or open the Finder sidebar, click your device).
- Under the General tab → Manage Backups, you can see and delete old device backups.
- Alternatively, navigate to
~/Library/Application Support/MobileSync/Backupin Finder (use Go → Go to Folder) and inspect backup folder sizes. Delete only backups you have confirmed are also in iCloud.
Step 5 — Let Crumb handle the rest automatically
If you are still short on space after the manual steps, or you want to be sure you have not missed anything, Crumb can identify and clean System Data, logs, temporary files, and purgeable space in a single pass. Its one-click Clean covers the same cache and temp paths as the Terminal commands above, plus system-level locations that require elevated access — without you having to type paths manually. After cleaning, Crumb shows you exactly how much space was freed, so you can confirm you have cleared enough headroom before starting the Tahoe installer. You can download Crumb and run a free cleanup right now if you need to act quickly.
Step 6 — Force macOS to reclaim purgeable space
Even after manual cleanup, macOS may still report purgeable space that the installer ignores. You can nudge the system to reclaim it:
- Open Terminal and run:
This flushes disk caches from inactive memory — a quick operation that may surface a small amount of additional free space.sudo purge - For purgeable APFS space specifically, the most reliable method is to temporarily copy a large file to your disk until free space is nearly full, then delete it. This forces APFS to actually mark purgeable blocks as free. However, this is only necessary in edge cases where the installer still refuses after manual cleanup.
After Freeing Space: Retry the Tahoe Update
- Verify you now have at least 25 GB free with
df -h /. - Open System Settings → General → Software Update.
- If the installer bundle is already downloaded, click Upgrade Now. If it was removed during cleanup, macOS will re-download it (it is stored separately from user caches and should not have been affected).
- Keep your Mac plugged in and connected to power for the full installation.
What Not to Delete
A few categories look tempting but carry real risk:
/Systemand/usr— these are protected system directories. Do not touch them.~/Library/Application Support— this holds app data, not caches. Deleting folders here can mean losing saved data, preferences, and documents for that app permanently.- Files you cannot identify — if you are unsure what a folder does, look it up before deleting. Crumb's "Is this safe to delete?" AI feature will explain any path and its risk level, which is useful when you encounter unfamiliar items during a manual cleanup.
The macOS Tahoe update storage error is solvable in most cases without buying a new drive or a subscription to anything. A targeted cleanup of caches, derived data, and old backups typically frees the 20–25 GB the installer needs. Work through the steps above in order, verify free space at each stage with df -h /, and the Tahoe installer should proceed without complaint.