---
name: mac-disk-analysis
description: Diagnose full disk on macOS when standard tools (du) are too slow. Use mdfind, check swap files, APFS snapshots, and common space hogs.
tags: [macos, disk, storage, cleanup, diagnostics]
---

# Mac Disk Analysis

Use when a MacBook is critically low on disk space and `du` commands time out or run too slowly.

## Quick Health Check

```bash
# Total vs used (df vs APFS — there can be a discrepancy)
df -h /
diskutil info / | grep -E "Volume Used Space|Volume Free Space|Purgeable"

# Check inode usage (rare but possible)
df -i /
```

## Finding Space Hogs When `du` Is Too Slow

When `du -sh ~` times out (common on 95%+ full disks), use these alternatives:

### 1. `mdfind` (Spotlight) — find large files instantly

```bash
# Find all files over 100MB in home directory
mdfind 'kMDItemFSSize > 100000000' -onlyin ~

# Over 500MB
mdfind 'kMDItemFSSize > 500000000' -onlyin ~
```

### 2. Quick estimates of known folders (these usually work)

```bash
du -sh ~/Library ~/Documents ~/Downloads ~/Desktop ~/.hermes 2>/dev/null
```

### 3. Check specific apps' data

```bash
# Chrome cache (can be 2-5GB)
du -sh ~/Library/Application\ Support/Google/Chrome

# Telegram (can have leftover update temp files)
ls -lh ~/Library/Application\ Support/Telegram\ Desktop/tupdates/temp/

# npm/pip caches
du -sh ~/.npm ~/Library/Caches/pip 2>/dev/null

# Docker (if installed)
ls -lh ~/Library/Containers/com.docker.docker/
```

## Swap Files — Silent 10GB+ Hog

macOS accumulates swap files in `/private/var/vm/` over days of uptime. Each file is 1GB.

```bash
ls -lh /private/var/vm/
```

If you see **8-10+ swap files + sleepimage**, that's 10+GB of disk. A reboot clears them all.

## APFS Snapshots (Time Machine Local)

APFS creates local snapshots even without an external backup drive. They're invisible to `df` but consume space.

```bash
# List local snapshots
tmutil listlocalsnapshots /

# Estimate snapshot sizes
for snap in $(tmutil listlocalsnapshotdates / | grep -v :); do
    tmutil listlocalsnapshots / | grep "$snap"
done

# Thin snapshots (free space by deleting oldest)
sudo tmutil thinlocalsnapshots / 5000000000 2>/dev/null
```

The discrepancy between `df` and `diskutil info` used space is often APFS snapshot + metadata overhead.

## Common Cleanup Suggestions (discuss with user before acting)

| Action | Typical Gain | Risk |
|---|---|---|
| **Reboot** | 8-12GB (swap + snapshots) | None |
| Clean `~/Downloads` (.dmg, .zip, old installers) | 1-5GB | Low |
| Clear Chrome cache | 1-3GB | Low |
| Remove Telegram update leftovers (`tupdates/temp/`) | 0.3-1GB | Low |
| Clear system logs (`/private/var/log/`) | 0.5-2GB | Low |
| Uninstall unused apps (Xcode, simulators, etc.) | 5-30GB | Medium |
| Delete old iOS backups (`~/Library/Application Support/MobileSync/Backup/`) | 5-20GB | Low |

> ⚠️ This is a work machine. Always discuss before deleting anything.

## macOS Versions

On High Sierra (10.13), some commands differ:
- `diskutil info /` works but "Purgeable" space may not be reported
- APFS is supported but local snapshots are less aggressive than modern macOS
- `tmutil thinlocalsnapshots` may not exist — use reboot instead