Clean One Xcode DerivedData Folder Instead of Deleting Every Build Cache

Identify the active build directory

Xcode can use a custom DerivedData location per workspace or command invocation. Deleting the default ~/Library/Developer/Xcode/DerivedData directory may therefore do nothing, or may remove unrelated project state. Inspect the build log's -derivedDataPath argument or the workspace build settings before cleaning.

For a command-line build, set a project-specific path explicitly:

xcodebuild -workspace App.xcworkspace -scheme App \
  -derivedDataPath /tmp/AppDerivedData build

This creates a clean, isolated reproduction without disturbing the developer's other projects.

Clean only after classifying the failure

DerivedData cleanup can help when generated intermediates or indexes are stale. It will not fix a signing certificate mismatch, missing simulator runtime, dependency resolution error, or unsupported Swift setting. Capture the first failing diagnostic and try a clean isolated path before deleting the default global cache.

If the isolated build passes, compare the old project's generated state and Xcode version. If it fails identically, the problem is likely in source, settings, dependency, or environment. Do not routinely clean on every CI run: that removes incremental build benefits and can hide undeclared inputs.

When a clean is required, record the exact directory and reason in the troubleshooting note. Keep Swift package caches and CocoaPods data separate from DerivedData; each has a different owner and repair path. A smaller cleanup is faster to reverse and gives a clearer diagnostic than removing all Xcode-related directories at once.

Use isolation to test the cleanup hypothesis

Build the same workspace with a new -derivedDataPath and compare the first diagnostic. If the isolated build passes, stale intermediates or indexes are plausible; if it fails with the same message, the root cause is probably source, settings, dependencies, signing, or the selected destination. This experiment is more informative than deleting the global directory and hoping the symptom changes.

DerivedData contains products, indexes, module caches, and intermediates tied to a project and configuration. It is not the place to repair a missing pod specification or a bad signing profile. Record the project path, scheme, configuration, Xcode version, and custom build location before removing anything. CI should use an intentional path per checkout or job so one build cannot consume another job's partial output.

If cleanup fixes the issue, add a regression check for the undeclared input that made stale state matter. A generated file, script phase, or environment value may not be included in the build dependency graph. Repeated cleanup is a symptom-management loop that makes builds slower and can hide missing dependencies. Keep the smallest cleanup necessary and verify that a clean checkout can build without a developer's private cache. If the isolated build passes, compare generated intermediates and inspect scripts for undeclared inputs; if it fails identically, investigate the first compiler or linker diagnostic instead of cleaning again.

Keep a short record of the cleanup experiment: old path, new path, selected scheme, configuration, Xcode version, and first diagnostic. This lets another developer reproduce the conclusion without deleting a global directory. Treat a passing clean build as evidence about stale state, not proof that the project has no missing inputs. Add a clean-checkout job periodically while preserving incremental caches for normal development.

If the same error occurs with a new path, stop cleaning and investigate the first compiler, linker, dependency, or signing diagnostic. DerivedData cleanup cannot repair a missing simulator runtime or an invalid profile. Keeping those categories separate makes a fix faster and prevents the team from normalizing slow full cleans.

Use an isolated path as an experiment before deleting the default directory. If the new path passes, compare generated files and build settings; if it fails identically, preserve the original evidence. Add a clean-checkout build periodically, but do not clean every run because that removes incremental-build benefits and can hide undeclared inputs. A fast build that depends on a private cache is not reproducible.

Before deleting a folder, capture the first error, active scheme, configuration, Xcode version, and DerivedData path. Build once with a new isolated path and compare the diagnostic. Do not mix DerivedData with Swift Package Manager caches, CocoaPods directories, simulator data, or signing assets; each has a different owner and repair path. CI should use a path scoped to the checkout or job and should not reuse incomplete output from another branch.