How to Clear the Swift Package Manager Cache Safely

There is more than one SwiftPM cache

Swift Package Manager stores different kinds of regenerable data at different scopes. A command-line package normally has a .build directory containing checkouts, repositories, build output, and workspace state. SwiftPM also maintains shared repository cache data so multiple projects do not have to fetch identical dependencies from the network every time.

Xcode adds another layer. When an app uses Swift packages, package checkouts and build products are commonly associated with the project's DerivedData. That means a package problem seen only inside Xcode may require a different cleanup from the same package built with the swift command-line tool.

The safest rule is to clean the narrowest layer that explains the symptom. Do not jump from one failed build to erasing every global cache. A project cleanup is quicker to recover from, works offline more often, and does not slow unrelated repositories.

Pick the correct SwiftPM command

SwiftPM documents three commands with intentionally different scope. swift package clean deletes build artifacts for the package. It is the first choice for stale compiled output, unexplained linker behavior, or a disk-space cleanup limited to one repository.

swift package reset resets the complete cache and build directory for the package. It is broader than clean and can force dependencies and workspace state for that package to be prepared again. Use it when clean did not resolve a corrupted or inconsistent local package workspace.

swift package purge-cache purges SwiftPM's global repository cache. This affects the download acceleration shared by projects, so the next resolve or build may need network access and take longer across multiple repositories. Use it for a genuinely oversized or broken global cache, not as routine build hygiene.

1. Commit or stash source changes, then confirm Package.swift and Package.resolved are present where your project expects them.
2. From the package root, run swift package clean and try the original build again.
3. If the package-local workspace is still inconsistent, run swift package reset, then resolve and build again.
4. Only if shared repository cache data is oversized or corrupted, run swift package purge-cache.
5. Verify the dependency graph and build before cleaning any Xcode-specific DerivedData.

Command availability follows your installed Swift toolchain. Run swift package --help to confirm the subcommands supported on that Mac.

Keep Package.resolved unless you intend to update versions

Package.resolved is dependency-resolution state, not disposable download cache. For applications, checking it into version control helps teammates and CI use the same resolved dependency versions. Deleting it can allow a future resolution to select different versions permitted by Package.swift.

That may be a valid troubleshooting step when you deliberately want a fresh resolution, but it changes the experiment. If the goal is only disk space or rebuilt artifacts, keep Package.resolved so the cleanup does not silently become a dependency upgrade.

Package.swift is source. Never remove or edit it as a cache-cleaning action. Likewise, do not delete a package's Sources, Tests, plugins, or local path dependencies. Generated .build content can come back; authored package files may not.

Clear Swift packages used by Xcode

For a package dependency used by an Xcode project, start with File > Packages > Reset Package Caches when the installed Xcode version offers that command. Then use File > Packages > Resolve Package Versions to restore the graph described by your project and resolution file. Menu names can vary across Xcode releases.

If the problem is tied to the project's compiled package artifacts, delete only that project's DerivedData through Xcode Settings > Locations or Finder. This removes generated app and package output together, after which the first build recompiles and reindexes.

Avoid deleting the entire DerivedData root if only one project is affected. Keep active projects warm and remove the relevant project folder. If several Xcode installations share your Mac, launch the intended version before resolving packages so its toolchain and platform support drive the rebuild.

Diagnose before you clean

For disk pressure, measure .build directories and the shared cache rather than guessing. A repository search for .build folders can reveal abandoned clones whose generated output is a better target than a global cache still accelerating active work.

For build failures, record the original error first. Authentication failures, unavailable Git hosts, invalid package manifests, incompatible tools versions, and checksum changes do not become fixed merely because downloads were removed. Cache deletion can hide the evidence and add a second network failure.

After cleanup, compare swift package show-dependencies or your Xcode package graph with the expected resolution. Run the relevant tests, not only a successful resolve. A dependency can download correctly and still be incompatible with your deployment target or toolchain.

A maintenance policy for teams and CI

Developer laptops benefit from selective cleanup: remove package-local build output when a repository becomes inactive, and keep the global repository cache while it still saves download time. CI runners are different; ephemeral workers can start clean, while persistent runners need a size limit and a cache key that includes the Swift toolchain and resolution state.

Do not make purge-cache a pre-build ritual. It discards reuse, increases network dependency, and can make rate limits or upstream outages more painful. Trigger it when measurement shows abnormal growth, when cache integrity is the diagnosed fault, or as a bounded maintenance job on persistent infrastructure.

Document the command and scope in incident notes. 'Cleared SwiftPM cache' is ambiguous; 'ran swift package clean in repository A' and 'purged the global repository cache' have very different blast radiuses and recovery costs.

Use AskClean for the surrounding developer storage

AskClean can inventory major developer-storage categories around SwiftPM, including per-project Xcode DerivedData, repository build artifacts, npm and other declared package caches, Simulator storage, and large unidentified folders. It explains whether an item is rebuildable and asks before deletion.

For SwiftPM itself, keep the official Swift commands as the source of truth for cache scope. AskClean is useful for finding which surrounding category is consuming space; it should not turn a precise package-manager operation into an unexplained bulk deletion.

SwiftPM command scope

Select by scope and recovery cost, not by the most aggressive command.

FAQ