Swift Package Manager のキャッシュを安全に削除する方法

SwiftPM のキャッシュは一つではない

Swift Package Manager は再生成可能なデータを複数の範囲に保存します。コマンドラインパッケージの .build にはチェックアウト、リポジトリ、ビルド成果物、ワークスペース状態があり、さらに複数プロジェクトで再利用する共有リポジトリキャッシュがあります。

Xcode はもう一層追加します。アプリで Swift Package を使う場合、チェックアウトとビルド成果物はプロジェクトの DerivedData に結び付くことがあります。そのため Xcode だけで起きる問題と swift build の問題では、掃除する場所が違います。

症状を説明できる最小範囲から始めてください。一度のビルド失敗で全グローバルキャッシュを消す必要はありません。プロジェクト単位なら復旧が速く、他のリポジトリを遅くしません。

目的に合う SwiftPM コマンドを選ぶ

swift package clean は現在のパッケージのビルド成果物を削除します。古いコンパイル結果、説明できないリンク問題、単一リポジトリの容量整理では最初に使うコマンドです。

swift package reset は現在のパッケージのキャッシュとビルドディレクトリ全体をリセットします。clean より広く、依存関係とワークスペース状態の再準備が必要になります。clean で直らないローカル状態の破損時に使います。

swift package purge-cache は SwiftPM のグローバルリポジトリキャッシュを消します。複数プロジェクトが依存関係を再取得し、ネットワークと時間が必要になります。共有キャッシュが実際に巨大または破損しているときだけ使ってください。

1. ソース変更をコミットまたは stash し、Package.swift と Package.resolved の存在を確認します。
2. パッケージのルートで swift package clean を実行し、元のビルドを再試行します。
3. ローカル状態がまだ不整合なら swift package reset を実行して再解決・再ビルドします。
4. 共有キャッシュの肥大化や破損を確認した場合だけ swift package purge-cache を実行します。
5. Xcode の DerivedData を消す前に、依存グラフとビルド結果を確認します。

利用できるサブコマンドはインストール済み Swift ツールチェーンに依存します。swift package --help で確認してください。

更新する意図がなければ Package.resolved を残す

Package.resolved はダウンロードキャッシュではなく、依存関係の解決結果です。アプリではバージョン管理に含めることで、チームと CI が同じバージョンを利用できます。削除すると Package.swift の許容範囲内で別バージョンが選ばれる場合があります。

新しい解決を意図したトラブルシューティングなら削除する場面はありますが、単なる容量整理とは別の操作です。ビルド成果物だけを作り直すなら残し、掃除を暗黙の依存更新にしないでください。

Package.swift、Sources、Tests、プラグイン、ローカルパス依存はソースです。.build は再生成できますが、作者が書いたファイルはキャッシュではありません。

Xcode で使う Swift Package を整理する

Xcode プロジェクトなら、利用中の版に File > Packages > Reset Package Caches がある場合はまず実行し、File > Packages > Resolve Package Versions でプロジェクトの解決状態を復元します。メニュー名は Xcode の版によって異なる場合があります。

問題がコンパイル済みパッケージ成果物に限られるなら、該当プロジェクトの DerivedData だけを削除します。Xcode Settings > Locations から場所を開き、毎日使う他プロジェクトのキャッシュは残します。

複数の Xcode をインストールしている場合は、再解決前に使う版を起動し、正しいツールチェーンとプラットフォームサポートでビルドしてください。

消す前に診断する

容量対策なら .build と共有キャッシュを測定し、使わなくなったリポジトリの成果物から処理します。現役プロジェクトを高速化している全体キャッシュを推測で捨てないでください。

ビルド障害なら最初のエラーを記録します。認証、Git ホスト、無効な manifest、ツールバージョン、チェックサムの問題は、ダウンロードを消しても直りません。むしろ証拠を消し、新しいネットワーク障害を加えることがあります。

掃除後は swift package show-dependencies や Xcode のグラフで解決結果を確認し、関連テストを実行します。ダウンロード成功だけでは、ツールチェーンや配備ターゲットとの互換性は証明できません。

開発用 Mac と CI の運用を分ける

開発用 Mac では、使わないリポジトリのローカル成果物だけを削除し、共有キャッシュが時間を節約している間は残します。CI の一時 Runner は毎回クリーンにでき、永続 Runner にはサイズ上限とツールチェーン・解決状態を含むキャッシュキーが必要です。

purge-cache を毎回のビルド前処理にしないでください。再利用を捨て、ネットワーク障害やレート制限の影響を増やします。異常な増加、整合性不良、管理された保守時間のときだけ実行します。

障害記録には範囲を明記します。「SwiftPM キャッシュを消した」ではなく、「リポジトリ A で clean」か「グローバルキャッシュを purge」かを区別してください。

AskClean で周辺の開発者ストレージを探す

AskClean はプロジェクト別 DerivedData、リポジトリ成果物、npm などの開発者キャッシュ、シミュレータ、分類不能な大容量フォルダを分け、再生成可能かを説明します。

SwiftPM 自体の範囲は公式 Swift コマンドを基準にしてください。AskClean は周辺で何が容量を使うかを発見するためのもので、精密なパッケージ操作を説明のない一括削除に置き換えません。

SwiftPM コマンドの作用範囲

最強のコマンドではなく、問題と復旧コストに合う範囲を選びます。

よくある質問