Swift Package Manager cache invalidation after Package.swift dependency version change

Dependency Resolution and Cache Boundaries

In Swift Package Manager (SPM), there is a strict functional boundary between resolution (determining which version to use), the package cache (downloaded source code), and build artifacts (compiled binaries in derived data).

When you modify a dependency version in Package.swift, SPM triggers a re-resolution cycle. This updates the Package.resolved file to lock the new version. This resolution process is the deterministic trigger for subsequent cache invalidation: if the resolved version or commit hash changes, the build system treats the previous build artifacts for that specific module as stale.

Package Cache vs. Derived Data

The package cache and derived data are consulted independently. A change in Package.swift does not purge the global package cache; instead, it prompts SPM to check if the newly resolved version already exists in the cache. If it does not, the source is downloaded. The existing version of the package remains in the cache until a manual purge or system cleanup occurs.

Guarantees for Fresh Artifacts

SPM guarantees fresh build artifacts under the following conditions:

• Version Change: A change in the semantic version or commit hash in Package.resolved invalidates the corresponding module's artifacts in derived data.
• Configuration Change: Changes to build settings (e.g., optimization levels or target platforms) typically trigger a rebuild of the affected dependencies.

Conversely, swift package clean only removes build artifacts. It does not invalidate the package cache or force a re-download of source code.

Verification and Recovery

To verify that a version change has triggered a rebuild, you can monitor the build logs for the specific module or use the following scoped approach to ensure a clean state:

# Remove build artifacts (DerivedData/build folder) without purging source cache
swift package clean

# To force a complete refresh of both source and artifacts (Manual)
rm -rf .build/checkouts
rm -rf .build/plugins
swift package resolve

Implementation Uncertainty

It is important to note that behavior may diverge between the swift build CLI and Xcode. Xcode manages its own DerivedData paths and may apply additional caching layers that can occasionally lead to "ghost" artifacts if the Package.resolved file is modified manually outside of the IDE. We assume Swift 5.9+ toolchains for this behavior.

Diagnostic Detail Needed: Are you observing a failure to rebuild despite a version change in Package.resolved, or are you specifically targeting the removal of old source versions from the disk?