Xcode Clean Build Folder vs Deleting DerivedData
AskClean Team · Updated 2026-08-20
Clean Build Folder clears the build products of the scheme you have open. Deleting DerivedData resets a wider set: build products plus indexes, module caches, and logs. For a broken build start with Clean Build Folder; for a corrupted index or real disk space, delete the DerivedData folder of that one project.
The difference is scope, not thoroughness
Product > Clean Build Folder (Shift-Command-K) operates inside the project and scheme you currently have open. It throws away the compiled products and intermediates for that context so the next build starts from source. It is scoped to one project, and it deliberately keeps things that are expensive to rebuild.
DerivedData is the top-level directory shared by every project that uses the default location — ~/Library/Developer/Xcode/DerivedData, one subfolder per project or workspace you have ever opened. Deleting one subfolder resets exactly that project. Deleting the whole directory makes every project you own rebuild and re-index on next open.
So the honest way to describe the pair is not "light clean" versus "deep clean". Clean Build Folder is narrow and cheap; deleting DerivedData is wide and costs you the index. Which one is right depends entirely on whether the thing that is broken lives inside the build products or outside them.
When a build breaks, start narrow
If the failure showed up right after you switched branches, changed a build configuration, or edited resource files, quit the running app and use Clean Build Folder first. It is the cheapest reset available, it preserves the index, and it gets you back to work in one build rather than one build plus several minutes of indexing.
Escalate to deleting that project's DerivedData folder when the symptoms are not really about build products: Xcode showing errors for code you already fixed, jump-to-definition landing in the wrong place, code completion that has stopped understanding your own types. Those are index symptoms, and Clean Build Folder does not touch the index.
There is one specific case worth knowing, because it is the usual reason "I cleaned and it did not help" turns into "I deleted DerivedData and it did": the precompiled module cache (ModuleCache.noindex) sits at the root of DerivedData, not inside any project's subfolder. Clean Build Folder never reaches it. When a module cache goes stale after an SDK or toolchain change, only removing it clears the error.
Neither command fixes an actual bug in your source or your dependencies. If the identical error survives a clean build, stop cleaning and read the compiler message — the cause is in project settings, Package.resolved, the selected SDK, or the code itself.
Neither one is a disk-cleanup strategy
Clean Build Folder is a diagnostic tool that happens to free some bytes. It can return space for the current project, but every other project's build products, every index, and the module cache all stay exactly where they were. Running it to reclaim disk is measuring the wrong thing.
If space is the actual goal, go the other way around: measure the DerivedData subfolders first, then delete the projects you have not opened in months. That is where the tens of gigabytes usually are — one-off clones you built once and never returned to.
Do not start with rm -rf. Finder lets you send the selected folders to the Trash, which stays recoverable until you empty it, and that difference matters the first time you delete the folder of a project that turns out to be building right now. The Terminal is worth it for automation, but only after you have confirmed the exact path.
Check the result instead of trusting a number
Record the size of DerivedData before you do anything, apply exactly one of the two options, then measure again. After Clean Build Folder, build the current scheme. After deleting a DerivedData folder, open Xcode and wait for the first build and the indexing pass to finish.
Doing it in that order separates the space you recovered from the price you paid to recover it. There is no universal figure to expect: the result depends on how many projects, configurations, and architectures have been built on that particular Mac.
Which one to reach for
| Situation | What to do | Cost of recovery |
|---|---|---|
| Build fails on the current scheme | Product > Clean Build Folder | One rebuild of this project. Indexes for every project are preserved. |
| Stale errors, broken jump-to-definition | ~/Library/Developer/Xcode/DerivedData/<project> | Full rebuild plus re-indexing, for that project only. |
| Errors survive Clean Build Folder after an SDK change | ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex | Modules are recompiled on the next build. Not reachable by Clean Build Folder. |
| You actually need disk space | ~/Library/Developer/Xcode/DerivedData | Delete the large stale subfolders; those projects rebuild when next opened. |
| Old simulator runtimes | Xcode Settings > Components | A separate category entirely. Neither command touches it. |
This table describes scope, not a promised number of gigabytes. Measure your own Mac before and after.
FAQ
Does Clean Build Folder delete DerivedData?
No. It clears the build products for the project and scheme you have open. It is not equivalent to deleting the shared DerivedData directory, which also holds the indexes, module cache, and logs for every project.
Is it safe to delete one project's DerivedData folder?
Yes. Everything in it is derived from your source, which Xcode regenerates. Your code and git history are untouched. The only cost is that the first build afterwards is a full build, followed by an indexing pass.
Do I need to quit Xcode first?
For deleting DerivedData by hand, yes — it avoids the indexer holding or recreating files while you remove them. For the built-in Clean Build Folder command, no; Xcode is doing it to itself.
Why is the error still there after cleaning?
Most likely the cause was never the cache. Check the compiler message, the scheme settings, dependency versions, Package.resolved, the selected SDK, and what actually changed on your current branch.
Clean Build Folder did nothing but deleting DerivedData fixed it. Why?
Usually the precompiled module cache. ModuleCache.noindex lives at the root of DerivedData rather than inside a project subfolder, so Clean Build Folder cannot reach it — deleting DerivedData does.
Sources