How to Free Up Space on Mac: The Developer's Guide

To free up space on a Mac, first find what is using it: System Settings > General > Storage for the overview, then du in Terminal for the detail. On a developer Mac the space is usually in rebuildable data: Xcode DerivedData, simulators, node_modules, Docker’s disk image and package caches, which you can delete without touching your own files.

TL;DR

• See the big folders: du -hd1 ~/Library 2>/dev/null | sort -h | tail -10
• Quit Xcode and clear build data: rm -rf ~/Library/Developer/Xcode/DerivedData/*
• Remove simulators for runtimes you no longer have: xcrun simctl delete unavailable
• Shrink package caches: brew cleanup, npm cache clean --force, pip3 cache purge
• If the numbers still don’t add up, check System Data and Time Machine local snapshots.

What is taking up space on my Mac?

Start with the built-in view. Open System Settings > General > Storage. The bar at the top splits usage into categories such as Applications, Documents, Developer, macOS and System Data, and the list below has an info button for each category. The Developer category covers Xcode project build files, Xcode caches, project archives, device support files and simulator support.

That view is a good start, but it does not tell you which folders are big. Terminal does. These commands only read sizes; they change nothing:

# How full is the disk that holds your data?
df -h /System/Volumes/Data

# Biggest folders in your home directory
du -xhd1 ~ 2>/dev/null | sort -h | tail -15

# Biggest folders in ~/Library (where most hidden usage lives)
du -hd1 ~/Library 2>/dev/null | sort -h | tail -10

# Biggest hidden dot folders (~/.npm, ~/.cache, ~/.gradle, ...)
du -sh ~/.[!.]* 2>/dev/null | sort -h | tail -10

-d1 limits the output to one level deep, -x stays on one volume, and sort -h sorts human-readable sizes so the biggest lines come last. If du prints “Operation not permitted” for some folders, macOS privacy protection is blocking Terminal; you can grant it Full Disk Access in System Settings > Privacy & Security > Full Disk Access, or just accept slightly low numbers.

On a developer Mac, the top of that list is almost always ~/Library/Developer, ~/Library/Containers (Docker Desktop lives there), ~/Library/Application Support and ~/Library/Caches, followed by dot folders like ~/.npm, ~/.rustup, ~/.gradle and any VM tool you use.

Mac storage full but no files? Where the space hides

If Finder shows a few gigabytes of documents but the disk is full, the space is in places Finder does not show by default:

• ~/Library is hidden in Finder. It holds Xcode data, simulators, app caches and containers.
• Dot folders in your home directory (anything starting with .) are hidden too. Package managers, toolchains and AI tools write gigabytes there.
• Disk images that look smaller or bigger than they are. Docker Desktop stores everything in a single sparse file, Docker.raw.
• System Data. Storage settings puts anything it can’t categorize into this bucket, so the mystery space usually shows up there. We cover it in detail in Mac System Data too large.
• Time Machine local snapshots and purgeable space. macOS counts snapshot space as available, so Finder and df can disagree by many gigabytes. See how to delete Time Machine local snapshots.

The developer hot spots, at a glance

Path	What it is	Safe to delete?	How it comes back
~/Library/Developer/Xcode/DerivedData	Build products, indexes, logs	Yes (quit Xcode first)	Next build and re-index
~/Library/Developer/CoreSimulator/Devices	One folder per simulator device	Yes for devices you don’t use	Create the device again in Xcode
Simulator runtimes (xcrun simctl runtime list)	Full iOS/watchOS/tvOS/visionOS images	Yes for versions you don’t test	Re-download in Xcode settings
~/Library/Developer/Xcode/iOS DeviceSupport	Symbol caches per device OS version	Yes for old OS versions	Copied again when you connect that device
node_modules in each project	Installed JS dependencies	Yes in inactive projects	npm install / pnpm install
~/Library/Containers/com.docker.docker/.../Docker.raw	Docker Desktop’s VM disk	Only via Docker’s own tools	Images re-pulled, containers recreated
~/Library/Caches/Homebrew, ~/.npm, pnpm store, pip/uv caches	Downloaded packages	Yes	Re-downloaded on next install
~/.ollama/models, ~/.cache/huggingface	Local AI model weights	Yes for models you don’t use	Pulled again (often many GB)
Git worktrees	Extra checkouts of a repo	Yes once merged and pushed	git worktree add

How to free up space from Xcode

Xcode is the single biggest consumer on most Apple developer Macs, and almost none of it is your source code. Check before you delete:

du -sh ~/Library/Developer/Xcode/DerivedData
du -sh ~/Library/Developer/CoreSimulator/Devices
xcrun simctl runtime list

DerivedData is pure build output. Quit Xcode, then:

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

Your next build is slower and Xcode re-indexes each project, and that is the only cost. The full walkthrough, including archives and device support, is in how to delete Xcode DerivedData.

Simulators take even more. Every device you have ever created keeps its own data folder, and each runtime is a multi-gigabyte disk image. The safe first step is to remove devices whose runtime is no longer installed:

xcrun simctl list devices
xcrun simctl delete unavailable

For runtimes, xcrun simctl runtime delete supports a --dry-run flag, so you can see what would go before anything is removed. More in how to delete Xcode simulators.

How to find and delete node_modules

node_modules folders are small individually and huge in aggregate, because every project, branch checkout and worktree has its own copy. List them with sizes:

find ~/Projects -name node_modules -type d -prune -exec du -sh {} + 2>/dev/null | sort -h

Change ~/Projects to wherever you keep code. -prune stops find from descending into nested node_modules, so each top-level folder is counted once. Delete the ones in projects you are not actively working on; npm install brings them back. The full guide, including how to delete them recursively without touching the wrong folder, is delete node_modules recursively on Mac.

How to shrink Docker’s disk usage

Docker Desktop keeps images, containers, volumes and build cache inside one file, Docker.raw. It is a sparse file, which means Finder and ls show its maximum size, not what it really uses. Compare the two:

du -sh  ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw   # real usage
du -Ash ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw   # apparent size

On the Mac this guide was tested on, the real usage was 10 GB while the apparent size was 460 GB. Never delete Docker.raw by hand while Docker has data you care about. With Docker running, check usage with docker system df, then reclaim it with Docker’s own commands (docker system prune removes stopped containers, unused networks, dangling images and build cache). Details and the volume caveats are in Docker.raw huge on Mac.

How to clear package-manager caches

Every package manager keeps a download cache that grows forever. They are all safe to clear; the cost is re-downloading on the next install. Each tool has a command that shows where its cache lives and a command that cleans it:

brew cleanup -n          # dry run: what Homebrew would remove
npm config get cache     # usually ~/.npm
pnpm store path
pip3 cache dir
uv cache dir

Then brew cleanup, npm cache clean --force, pnpm store prune, pip3 cache purge and uv cache clean. brew cleanup also removes old versions of installed formulae, so it often frees more than ~/Library/Caches/Homebrew alone suggests. Our guide to Library caches covers each tool and what is safe to delete in ~/Library/Caches generally.

How to remove local AI models

If you run models locally, they are often the largest single files on your disk. By default Ollama stores models in ~/.ollama/models and Hugging Face tools use ~/.cache/huggingface. Check with ollama list and du -sh, and remove models with ollama rm <name>. See where Ollama and Hugging Face models are stored for custom locations and the other tools that keep their own copies.

How to clean up old git worktrees

Worktrees are full working copies, often with their own node_modules and build folders. List them per repo and remove the ones you are done with:

git worktree list
git worktree remove ../my-repo-feature-x
git worktree prune

git worktree remove refuses to delete a worktree with modified tracked files or untracked files unless you pass --force, which is exactly the safety you want. Removing a worktree does not delete its branch, so committed work stays in the repository. Full guide: git worktree remove and prune.

The non-developer basics still matter

Once the developer data is handled, run through the usual list:

• Empty the Trash. Files in the Trash still use space. Storage settings can empty it automatically for items older than 30 days.
• Downloads. Old installers and disk images add up. Sort ~/Downloads by size in Finder.
• Storage recommendations. Storage settings offers Store in iCloud, Optimize Storage, Empty Trash Automatically and Reduce Clutter. Read what each one does before you turn it on; Store in iCloud, for example, moves files off the Mac and downloads them on demand.
• iPhone and iPad backups. Local device backups are stored under ~/Library/Application Support/MobileSync/Backup on most setups and can be large.

How to free up space on a MacBook Pro specifically

Nothing about the process is different on a MacBook Pro, MacBook Air, iMac or Mac mini. macOS stores the same data in the same places. The difference is how quickly you hit the wall: a 512 GB or smaller SSD fills up after a few Xcode versions, a Docker setup and a couple of local models. Laptops also keep a sleep image in /private/var/vm for hibernation; leave it alone, macOS manages it.

Why the numbers never quite add up

You may notice that Storage settings, Finder, df and du all report different totals. Three things cause most of it:

• Purgeable space. macOS counts space it can reclaim on its own, such as local snapshots and some caches, as available. df doesn’t.
• APFS clones and hard links. Two files can share the same blocks on disk. pnpm’s store uses hard links, and APFS can clone files on copy, so adding up file sizes counts the same data twice.
• Sparse files. Files like Docker.raw report a size far larger than the space they use, as shown above.

This is why “I deleted 40 GB and only got 15 GB back” happens: some of what you deleted was never using its own space.

Do it in one click with DevCleanup

DevCleanup is a native macOS app (~7 MB, macOS 14+, Apple silicon and Intel) that finds all of the above in one scan. Smart Clean clears caches, logs and Xcode DerivedData for free; the Simulators, Projects, Docker, AI Models and Worktrees screens let you review each developer category; Space Lens shows where the rest of your disk went; and the System Data screen covers Time Machine snapshots, device backups and old installers. The developer screens count real space, so APFS clones and hard links are not double counted, and the number they promise is the number you get back. It never deletes a git repo, flags worktrees with uncommitted or unpushed work and leaves them unselected, removes simulators through xcrun simctl and worktrees through git worktree remove, and logs everything in History with how to restore it. There is no account and no analytics.

Download DevCleanup. Scanning is free; Pro ($29 one-time) unlocks the developer cleanup actions. If you are comparing tools, see the best Mac cleaner for developers.