Fixing the 'Your Disk is Almost Full' Error: A Developer's Guide to macOS Cleanup

The SSD Wall: Why your Mac is stallingYou are in the middle of a deep-work session when it happens: your system starts to stutter, apps stop responding, and that dreaded notification appears: Your disk is almost full. On a 256GB or even a 512GB MacBook, this wall comes faster than you'd expect.

For developers, the fix isn't as simple as deleting a few old photos. The real culprits are buried in hidden library caches, forgotten build artifacts, and massive container images. Clicking 'Optimize' in the macOS system settings barely scratches the surface of the technical debt living in your ~/Library folder.

Identify the Real Space HogsThe 'System Data' category in the macOS storage GUI is a black box. It often miscalculates usage, leaving you guessing where the bloat lives. Use the Terminal to get the ground truth.

First, check your overall disk summary:

df -h /

To find which directories are actually eating your storage, run this command to see the top 10 largest folders in your home directory:

du -sh ~/* 2>/dev/null | sort -rh | head -n 10

Don't be surprised if ~/Library is at the top. Let's look at the specific developer tools that turn your SSD into a graveyard of old projects.

Solution 1: Purge Xcode Technical DebtIf you have ever developed for iOS or macOS, Xcode is likely your biggest storage enemy. It accumulates build data and logs that rarely clean themselves up.

Clear Derived DataThe DerivedData folder stores intermediate build results and indexes. For active developers, this folder can easily swell to 30GB or more. It is entirely safe to delete; Xcode will simply rebuild what it needs next time you hit 'Run'.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

Delete Old iOS SimulatorsEvery Xcode update often leaves behind older simulator runtimes. Each one can occupy 5GB to 10GB of space.

# List all runtimes to see what's installed
xcrun simctl list devices

# Wipe all unavailable (outdated) simulators
xcrun simctl delete unavailable

Solution 2: Clean Up Package ManagersTools like Homebrew and npm are designed for speed, which means they cache every version of every package you have ever touched.

Homebrew CleanupHomebrew keeps old versions of formulae and unfinished downloads. Reclaim space with:

brew cleanup -s

If you want to see exactly how many gigabytes you'll save before committing, run brew cleanup -n first.

Node.js and Yarn CachesGlobal caches for JavaScript packages grow indefinitely. If you haven't cleared these in months, you're likely sitting on several gigabytes of redundant files.

# Force clear the npm cache
npm cache clean --force

# Purge the Yarn cache
yarn cache clean

Solution 3: Pruning Docker ContainersDocker is arguably the most aggressive consumer of Mac storage. Between unused images, stopped containers, and dangling volumes, it's common to find 50GB+ of 'ghost' data.

# Remove dangling images, containers, and networks
docker system prune

# For a total reset, remove ALL unused images and volumes
docker system prune -a --volumes

Check your Docker Desktop settings. If the 'Disk image location' file (Docker.raw) has ballooned, you might need to lower the 'Disk image size' limit in the Resources tab.

Solution 4: Hunting Large Files ManuallyA forgotten 2GB database dump or a 1GB log file can hide in plain sight. Use the find command to locate files larger than 500MB:

sudo find / -type f -size +500M -exec ls -lh {} + 2>/dev/null

Pro tip: The 2>/dev/null suffix filters out the 'Permission Denied' noise from system-protected folders.

Verification: Confirming the FixAfter your cleanup, don't just trust that the error is gone. Verify your work.

• Run df -h / again. Aim for at least 20GB to 30GB of free space.- macOS uses free space for 'Swap' memory. If you have less than 10% of your disk free, your Mac will feel sluggish even if the warning disappears.- Restart your machine. A reboot clears /private/var/folders, which often holds temporary system data that Terminal commands won't touch.## Lessons Learned- Trust the Terminal: The GUI storage breakdown is an estimate; du is the truth.- Schedule your maintenance: Run brew cleanup once a month.- Target the Library: Most developer bloat lives in ~/Library/Caches and ~/Library/Developer.- Offload Docker: If you are constantly out of space, move your Docker virtual disk to an external SSD via the Docker Desktop settings.