Swift-Package-Manager-Cache (SPM) sicher leeren

SwiftPM hat mehr als einen Cache

Swift Package Manager speichert verschiedene Arten neu erzeugbarer Daten auf verschiedenen Ebenen. Ein Kommandozeilenpaket hat normalerweise ein .build-Verzeichnis mit Checkouts, Repositories, Build-Ausgaben und Workspace-Zustand. Daneben pflegt SwiftPM gemeinsame Repository-Cache-Daten, damit nicht jedes Projekt dieselben Abhängigkeiten jedes Mal neu aus dem Netz laden muss.

Xcode fügt eine weitere Ebene hinzu. Nutzt eine App Swift-Pakete, gehören Paket-Checkouts und Build-Produkte meist zum DerivedData des Projekts. Ein Paketproblem, das nur in Xcode auftritt, braucht daher womöglich eine andere Bereinigung als dasselbe Paket, wenn du es mit dem Kommandozeilenwerkzeug swift baust.

Die sicherste Regel: Bereinige die engste Ebene, die das Symptom erklärt. Ein einzelner fehlgeschlagener Build ist kein Grund, sämtliche globalen Caches zu löschen. Nach einer Bereinigung auf Projektebene bist du schneller wieder arbeitsfähig, sie klappt öfter auch offline und bremst keine anderen Repositories aus.

Den richtigen SwiftPM-Befehl wählen

SwiftPM dokumentiert drei Befehle mit bewusst unterschiedlichem Wirkungsbereich. swift package clean löscht die Build-Artefakte des Pakets. Das ist die erste Wahl bei veralteten Kompilaten, unerklärlichem Linker-Verhalten oder wenn du nur in einem Repository Platz schaffen willst.

swift package reset setzt den kompletten Cache und das Build-Verzeichnis des Pakets zurück. Das reicht weiter als clean: Abhängigkeiten und Workspace-Zustand des Pakets müssen danach womöglich neu vorbereitet werden. Nutze reset, wenn clean einen beschädigten oder inkonsistenten lokalen Paket-Workspace nicht repariert hat.

swift package purge-cache leert den globalen Repository-Cache von SwiftPM. Das betrifft die Download-Beschleunigung, die sich alle Projekte teilen: Die nächste Auflösung oder der nächste Build braucht womöglich Netzwerkzugriff und dauert in mehreren Repositories länger. Setze den Befehl bei einem tatsächlich übergroßen oder defekten globalen Cache ein, nicht als routinemäßige Build-Hygiene.

1. Committe deine Änderungen am Quellcode oder lege sie mit git stash beiseite und prüfe, ob Package.swift und Package.resolved dort liegen, wo dein Projekt sie erwartet.
2. Führe im Stammverzeichnis des Pakets swift package clean aus und starte den ursprünglichen Build erneut.
3. Ist der lokale Workspace des Pakets weiterhin inkonsistent, führe swift package reset aus, löse die Abhängigkeiten neu auf und baue erneut.
4. Führe swift package purge-cache nur aus, wenn der gemeinsame Repository-Cache übergroß oder beschädigt ist.
5. Prüfe Abhängigkeitsgraph und Build, bevor du Xcode-spezifisches DerivedData bereinigst.

Welche Unterbefehle verfügbar sind, hängt von deiner installierten Swift-Toolchain ab. Prüfe sie auf dem jeweiligen Mac mit swift package --help.

Package.resolved behalten, solange du keine Versionen ändern willst

Package.resolved hält den Stand der Abhängigkeitsauflösung fest und ist kein wegwerfbarer Download-Cache. Bei Apps sorgt die Datei unter Versionskontrolle dafür, dass Team und CI dieselben aufgelösten Versionen verwenden. Löschst du sie, kann eine spätere Auflösung andere Versionen wählen, die Package.swift zulässt.

Das kann bei der Fehlersuche ein sinnvoller Schritt sein, wenn du bewusst neu auflösen willst – aber dann änderst du das Experiment. Geht es nur um Speicherplatz oder neu gebaute Artefakte, behalte Package.resolved, damit aus der Bereinigung nicht unbemerkt ein Upgrade deiner Abhängigkeiten wird.

Package.swift ist Quellcode: Lösche oder bearbeite die Datei nie im Rahmen einer Cache-Bereinigung. Dasselbe gilt für Sources, Tests, Plugins und lokale Pfadabhängigkeiten eines Pakets. Generierte Inhalte in .build kommen zurück, selbst geschriebene Paketdateien womöglich nicht.

Swift-Pakete in Xcode bereinigen

Bei einer Paketabhängigkeit in einem Xcode-Projekt beginnst du mit File > Packages > Reset Package Caches, sofern deine Xcode-Version diesen Befehl anbietet. Stelle dann mit File > Packages > Resolve Package Versions den Graphen wieder her, den dein Projekt und Package.resolved beschreiben. Die Menünamen können sich zwischen Xcode-Versionen unterscheiden.

Hängt das Problem an den kompilierten Paket-Artefakten des Projekts, lösche nur das DerivedData dieses Projekts – über Xcode Settings > Locations oder im Finder. Damit entfernst du die generierten App- und Paketausgaben gemeinsam; der erste Build danach kompiliert und indiziert alles neu.

Lösche nicht das gesamte DerivedData-Verzeichnis, wenn nur ein Projekt betroffen ist: Entferne den passenden Projektordner und lass die Caches aktiver Projekte bestehen. Sind mehrere Xcode-Installationen auf deinem Mac, starte vor dem Auflösen der Pakete die vorgesehene Version, damit deren Toolchain und Plattformunterstützung den Neuaufbau bestimmen.

Vor dem Löschen diagnostizieren

Wird der Speicherplatz knapp, miss die .build-Ordner und den gemeinsamen Cache, statt zu raten. Eine Suche nach .build-Ordnern in deinen Repositories fördert oft aufgegebene Klone zutage, deren generierte Ausgaben ein besseres Ziel sind als ein globaler Cache, der deine aktive Arbeit noch beschleunigt.

Bei Build-Fehlern sicherst du zuerst die ursprüngliche Fehlermeldung. Authentifizierungsfehler, nicht erreichbare Git-Hosts, ungültige Paketmanifeste, inkompatible Tools-Versionen und geänderte Prüfsummen verschwinden nicht, nur weil Downloads gelöscht wurden. Das Löschen des Caches kann die Spuren verwischen und einen zweiten Netzwerkfehler obendrauf setzen.

Vergleiche nach der Bereinigung swift package show-dependencies oder den Paketgraphen in Xcode mit der erwarteten Auflösung. Führe die relevanten Tests aus, nicht nur eine erfolgreiche Auflösung: Eine Abhängigkeit kann sich korrekt herunterladen lassen und trotzdem nicht zu deinem Deployment-Target oder deiner Toolchain passen.

Eine Wartungsregel für Teams und CI

Auf Entwickler-Laptops lohnt sich selektives Aufräumen: Entferne die paketlokalen Build-Ausgaben, wenn ein Repository inaktiv wird, und behalte den globalen Repository-Cache, solange er Downloadzeit spart. Bei CI-Runnern ist es anders: Kurzlebige Worker können sauber starten, persistente Runner brauchen ein Größenlimit und einen Cache-Schlüssel, der Swift-Toolchain und Auflösungsstand einbezieht.

Mach purge-cache nicht zum Ritual vor jedem Build. Damit verzichtest du auf Wiederverwendung, bist stärker vom Netz abhängig, und Rate-Limits oder Ausfälle bei Upstream-Hosts treffen dich härter. Sinnvoll ist der Befehl, wenn Messungen ungewöhnliches Wachstum zeigen, wenn ein defekter Cache als Ursache feststeht oder als begrenzter Wartungsjob auf persistenter Infrastruktur.

Halte in Incident-Notizen Befehl und Umfang fest. „SwiftPM-Cache geleert“ ist mehrdeutig; „swift package clean in Repository A ausgeführt“ und „globalen Repository-Cache geleert“ haben eine völlig unterschiedliche Reichweite und ganz andere Wiederherstellungskosten.

AskClean für den Entwicklerspeicher rund um SwiftPM

AskClean kann die großen Kategorien des Entwicklerspeichers rund um SwiftPM erfassen: Xcode DerivedData pro Projekt, Build-Artefakte in Repositories, npm und andere deklarierte Paket-Caches, Simulator-Speicher und große, nicht zugeordnete Ordner. Die App erklärt, ob sich ein Eintrag neu erzeugen lässt, und fragt vor dem Löschen nach.

Für SwiftPM selbst bleiben die offiziellen Swift-Befehle maßgeblich, wenn es um den Umfang des Caches geht. AskClean hilft dir herauszufinden, welche benachbarte Kategorie Platz belegt – aus einem präzisen Paketmanager-Befehl soll dabei keine unerklärte Massenlöschung werden.

Wirkungsbereich der SwiftPM-Befehle

Wähle nach Umfang und Wiederherstellungskosten – nicht einfach den aggressivsten Befehl.

FAQ