Was ist pnpm? Unterschied zu npm und Yarn

Was ist pnpm?

Pnpm ist ein Paketmanager für JavaScript und Node.js Projekte, der Pakete einmal in einem gemeinsamen, inhaltsadressierten Speicher ablegt und sie per Hardlink in jedes Projekt einbindet. Das spart dabei Festplattenspeicher und macht die Abhängigkeitsauflösung strenger als bei npm oder Yarn.

Talha Aslan und sein Team vergleichen bei individuellen Softwareprojekten regelmäßig Einrichtungszeit und Speicherbedarf. Dabei setzt sich pnpm häufig durch. Allerdings hängt die richtige Wahl immer von Projektgröße, Teamgewohnheiten und vorhandener Toolchain ab. Deshalb lohnt sich zunächst ein Blick darauf, wie npm und Yarn arbeiten.

Zunächst zur Ausgangslage: Npm und Yarn Classic kopieren Abhängigkeiten für jedes Projekt in einen eigenen node_modules Ordner. Pnpm schreibt dieselbe Paketversion dagegen nie zweimal auf die Platte. Es verknüpft stattdessen mit der Datei im zentralen Speicher. Dadurch wächst der Unterschied, je mehr Projekte auf derselben Maschine laufen.

Warum Wurde pnpm Entwickelt?

Das pnpm Projekt entstand als Antwort auf einen einfachen Kostenfaktor: npm lädt Abhängigkeiten für jedes Projekt erneut herunter und kopiert sie erneut, was Speicherplatz und Zeit kostet. Die offizielle pnpm Dokumentation nennt als Ziel, Paketdateien in einem einzigen inhaltsadressierten Speicher zu halten und Projekte damit zu verknüpfen.

Dadurch muss ein Paket in einer bestimmten Version nicht für Dutzende Projekte erneut auf die Platte geschrieben werden. Außerdem fügt das Werkzeug dem Speicher nur die geänderten Dateien hinzu, wenn sich eine neue Version nur in wenigen Dateien von der alten unterscheidet. Der Rest liegt dort also bereits.

Zudem flachen npm und Yarn Classic node_modules auf eine einzige Ebene ab. Dadurch konnte Code auf Pakete zugreifen, die ein Projekt in der package.json nie deklariert hatte. Das pnpm Team betrachtete das also als bewussten Designfehler und baute stattdessen eine andere Ordnerstruktur.

Wie Funktioniert das Speichermodell von pnpm?

Die Installation läuft in drei Schritten ab: Zuerst löst das Werkzeug Abhängigkeiten auf und lädt sie in den zentralen Speicher. Danach berechnet es die node_modules Struktur. Schließlich verknüpft es die gespeicherten Dateien per Hardlink mit dem Projekt. Die offizielle Dokumentation beschreibt diese Reihenfolge außerdem als schneller als den klassischen Ablauf aus Auflösen, Herunterladen und Schreiben.

Konkret liegt der Speicher auf einem einzigen Laufwerk, und jede Paketversion liegt dort genau einmal. Braucht ein neues Projekt dieselbe Version, verknüpft das Werkzeug mit der vorhandenen Kopie, statt sie erneut herunterzuladen. Folglich sinkt auch der Netzwerkverkehr, weil das Paket bereits im lokalen Speicher liegt.

Vor allem sollten Speicher und Projekte auf demselben Laufwerk und Dateisystem liegen. Andernfalls muss das Werkzeug Dateien kopieren statt verknüpfen, und der Vorteil schrumpft. Daher empfehlen wir, das beim Einrichten eines CI/CD Servers von Anfang an zu berücksichtigen.

Was Unterscheidet Symlink und Hardlink?

Ein Hardlink wirkt wie ein zweiter Name für dieselbe Datei auf der Festplatte. Konkret existiert der Inhalt nur einmal, ist aber aus mehreren Ordnern erreichbar. Ein Symlink dagegen funktioniert wie eine Verknüpfung, die auf den Pfad der echten Datei zeigt.

Zunächst verknüpft das Werkzeug die echten Paketdateien aus dem Speicher per Hardlink mit jedem Projekt und baut die node_modules Struktur zusätzlich mit Symlinks auf. Direkte Abhängigkeiten liegen also als Symlink im Wurzelverzeichnis, und diese Symlinks zeigen auf die echten Ordner innerhalb von node_modules/.pnpm.

Unter Windows nutzt das System bei deaktiviertem Entwicklermodus zudem Junctions statt Symlinks. Das hält dieselbe Logik auch im Windows Dateisystem funktionsfähig. Für den Anwender bleibt dieser Plattformunterschied dadurch unsichtbar.

Wie Spart pnpm Festplattenspeicher?

Nutzen zehn verschiedene Projekte mit npm dasselbe Paket, kopiert npm dieses Paket zehnmal auf die Platte. Konkret liegt das gleiche Paket mit diesem Werkzeug nur einmal im Speicher, und alle zehn Projekte verknüpfen mit dieser einen Kopie. Dadurch sinkt der gesamte Speicherbedarf deutlich.

Vor allem Teams, die viele kleine Projekte oder ein Monorepo betreiben, bemerken diesen Vorteil als Erstes. Die Struktur eines Monorepos ist dabei ein eigenes Thema. Wir behandeln sie bereits ausführlich in unserem Monorepo Ratgeber, deshalb wiederholen wir sie hier nicht.

Ändern sich zwischen zwei Versionen eines Pakets zudem nur wenige Dateien, ergänzt das Werkzeug lediglich diese geänderten Dateien im Speicher. Der Rest liegt also bereits dort und belegt beim zweiten Mal keinen zusätzlichen Platz.

Wie Unterscheidet Sich die node_modules Struktur von npm und Yarn?

Npm und Yarn Classic flachen jede Abhängigkeit, direkt wie indirekt, in die Wurzel von node_modules ab. Dieses Werkzeug platziert standardmäßig also nur die direkten Abhängigkeiten, also jene aus der package.json, in diesem Wurzelverzeichnis.

Konkret liegen indirekte Abhängigkeiten als echte Dateien im internen Ordner node_modules/.pnpm, und die Pakete im Wurzelverzeichnis zeigen per Symlink auf diesen Ordner. Die Struktur wird dadurch nicht tiefer, sie folgt lediglich einer flachen, aber geschichteten Logik.

• Npm und Yarn Classic bauen ein einziges, flaches node_modules.
• Dieses Werkzeug hält nur direkte Abhängigkeiten im Wurzelverzeichnis. Echte Dateien liegen unter .pnpm.
• Verträgt Ihre Toolchain keine Symlinks, stellen Sie die Einstellung nodeLinker auf hoisted um und erhalten ein npm ähnliches, flaches Layout.

Was Ist das "Phantom Dependency" Problem?

Eine Phantomabhängigkeit ist ein Paket, das Ihr Projekt nie in der package.json deklariert hat, das Ihr Code aber trotzdem importieren kann. Das abgeflachte node_modules bei npm und Yarn platziert dieses Paket also im Wurzelverzeichnis, sodass Ihr Code unbemerkt darauf zugreift.

Das Problem zeigt sich allerdings erst später: Das Paket ist eigentlich eine indirekte Abhängigkeit einer anderen Bibliothek, die Sie tatsächlich nutzen. Entfernen Sie diese Bibliothek oder ändern Sie ihre Version, kann Ihr Projekt plötzlich brechen, denn Sie hatten das Phantompaket nirgendwo direkt angefordert.

Die Standardstruktur dieses Werkzeugs verweigert nämlich nicht deklarierten Paketen den Zugriff über das Wurzelverzeichnis. Deshalb sehen Sie bei der ersten Installation manchmal eine Fehlermeldung "Modul nicht gefunden", die eine solche versteckte Abhängigkeit aufdeckt. Das ist also die Folge des strengen Verhaltens, kein Fehler.

Warum Ist pnpm Strenger bei der Abhängigkeitsauflösung?

Die offizielle FAQ von pnpm hält fest, dass das flache node_modules von npm und Yarn einen verbreiteten Fehler verdeckt: Ein Projekt kann ein Paket nutzen, das es nie deklariert hat, ohne dass es jemand merkt. Dieses Werkzeug macht diesen Fehler also sichtbar, statt ihn zu verstecken.

Bricht ein Projekt nach dem Umstieg wegen einer solchen versteckten Abhängigkeit, schlägt die Dokumentation drei Lösungen vor: das fehlende Paket direkt mit dem add Befehl ergänzen, die Einstellung nodeLinker auf hoisted umstellen für ein npm ähnliches, flaches Layout, oder über einen .pnpmfile.mjs readPackage Hook die fehlende Abhängigkeit zum Manifest eines Pakets hinzufügen.

Diese Strenge wirkt zunächst wie zusätzliche Arbeit. Dennoch zeigt sie klar, von welchen Paketen ein Projekt wirklich abhängt. Das Team kann den Abhängigkeitsbaum dadurch mit deutlich mehr Sicherheit verwalten.

Wie Starten Sie mit der Installation?

Sie können das Werkzeug über Corepack aktivieren, das mit Node.js mitgeliefert wird, oder es global über npm installieren. Beide Wege machen also den Befehl im Terminal verfügbar.

Danach besteht der erste Schritt in einem bestehenden Projekt darin, den install Befehl auszuführen. Dieser löst Abhängigkeiten auf, lädt sie in den Speicher und verknüpft node_modules per Hardlink. Starten Sie dagegen ein neues Projekt, legt der init Befehl eine einfache package.json für Sie an.

Zunächst sollten alle im Team dieselbe Version nutzen. Andernfalls kann die Lockdatei auf verschiedenen Maschinen unterschiedliche Ergebnisse liefern. Deshalb hält das Festschreiben der Versionsnummer in einer Projektdatei das ganze Team konsistent.

Ist Ihre Netzwerkverbindung langsam, oder nutzt Ihr Unternehmen eine eigene Registry, müssen Sie das außerdem in der Konfigurationsdatei des Werkzeugs festlegen. Andernfalls versuchen Pakete, von der öffentlichen Registry zu kommen.

Wie Prüfen Sie eine Frische Installation?

Um die Installation zu prüfen, fragen Sie im Terminal die Versionsnummer ab und testen anschließend den install Befehl in einem kleinen Testprojekt. Läuft der Befehl fehlerfrei durch und entsteht node_modules in der erwarteten Form, war die Einrichtung also erfolgreich.

Erhalten Sie dagegen eine Fehlermeldung, prüfen Sie zuerst Ihre Netzwerkverbindung und danach die Registry Einstellung in der Konfigurationsdatei. Diese Kombination löst die meisten Probleme schnell.

pnpm und npm im Vergleich: Was Sind die Hauptunterschiede?

Stellt man beide Werkzeuge nebeneinander, werden die Unterschiede deutlicher. Konkret fasst die folgende Tabelle die häufigsten Fragen aus dem Alltag zusammen.

Die Befehlsnamen bleiben größtenteils gleich. Install, add und run entsprechen weitgehend ihren npm Gegenstücken. Deshalb fällt einem Team die Umstellung meist leicht.

pnpm und Yarn im Vergleich: Wo Liegt der Unterschied?

Zunächst flacht Yarn Classic node_modules ähnlich wie npm ab. Die neueren Yarn Versionen (Berry) folgen stattdessen ihrem eigenen Plug'n'Play Modell. Dieses Werkzeug verfolgt dagegen ein eigenes, symlinkbasiertes Modell, das sich von beiden Ansätzen unterscheidet.

Beim Speicherplatz schlägt das gemeinsame Speichermodell also die Gewohnheit von Yarn Classic, für jedes Projekt eine eigene Kopie zu halten. Das Plug'n'Play Modell von Yarn Berry entfernt node_modules ebenfalls weitgehend, benötigt aber für manche Werkzeuge zusätzliche Konfiguration.

Welche Wahl zu Ihrem Team passt, hängt davon ab, wie gut Ihre übrigen Werkzeuge Symlinks oder Plug'n'Play unterstützen. Deshalb empfehlen wir, den Umstieg zuerst in einem kleinen Pilotprojekt zu testen.

Was Sind pnpm Workspaces, und Wie Unterstützen Sie ein Monorepo?

Workspaces gruppieren mehrere Pakete in einem Repository und installieren sie gemeinsam. Das ist also die fest eingebaute Monorepo Unterstützung des Werkzeugs. Konkret basiert sie auf einer pnpm-workspace.yaml Datei im Projektstamm.

Die Datei listet die Ordnermuster auf, in denen Pakete liegen, etwa packages/*. Nutzt ein Projekt bereits das workspaces Feld von npm, Yarn oder Bun und existiert noch keine pnpm-workspace.yaml, legt der install Befehl automatisch eine solche Datei mit denselben Mustern an. Eine vorhandene Datei überschreibt er aber nie.

• Das workspace Protokoll garantiert, dass ein Paket mit einem anderen lokalen Paket verknüpft wird.
• Wird ein Paket gepackt oder veröffentlicht, schreibt das Werkzeug workspace Referenzen in normale Versionsbereiche um.
• Dank der gemeinsamen Lockdatei verwaltet das Team den gesamten Workspace über eine einzige pnpm-lock.yaml.

Vorteile und Nachteile eines Monorepos selbst behandeln wir bereits in unserem Monorepo Ratgeber. Hier geht es nur darum, wie dieses Werkzeug diese Struktur unterstützt.

Wozu Dient die Datei pnpm-lock.yaml?

Konkret hält die Lockdatei die genaue Version und den Abhängigkeitsbaum jedes installierten Pakets fest. Teilt das Team diese Datei, installiert jede Maschine dieselben Versionen, was das klassische Problem "bei mir funktioniert es" weitgehend beseitigt.

Daher sollten Sie diese Datei in die Versionskontrolle aufnehmen. Andernfalls kann jeder Entwickler mit einem anderen Abhängigkeitsbaum enden. Ebenso installiert ein CI/CD Server üblicherweise genau die Versionen aus der Lockdatei, sodass die Build Umgebung der lokalen Umgebung entspricht.

Wir raten davon ab, die Lockdatei von Hand zu bearbeiten. Nutzen Sie stattdessen die Befehle add, update oder remove, um die Datei aktuell zu halten. Eine manuelle Änderung kann sonst die erwartete Struktur zerstören und die nächste Installation fehlschlagen lassen.

Ebenso lohnt sich bei der Code Review ein Blick auf Änderungen der Lockdatei. Ein unerwarteter Versionssprung zeigt oft, dass jemand den falschen Befehl ausgeführt hat oder dass sich eine versteckte Abhängigkeit selbst aktualisiert hat. Diese kleine Gewohnheit deckt also große Versionskonflikte frühzeitig auf.

Wie Wechseln Sie von npm oder Yarn zu pnpm?

Dieses Werkzeug bietet einen import Befehl, der aus einer vorhandenen package-lock.json, npm-shrinkwrap.json oder yarn.lock eine pnpm-lock.yaml erzeugt. Konkret liest der Befehl die Versionsangaben aus der alten Lockdatei und überträgt sie in das eigene Format.

1. Installieren Sie das Werkzeug in Ihrem Projekt und führen Sie den import Befehl aus.
2. Enthält Ihr Projekt einen Workspace (Monorepo), definieren Sie vor dem Import eine pnpm-workspace.yaml. Sonst fehlen die Abhängigkeiten der Workspace Pakete.
3. Führen Sie den install Befehl aus und prüfen Sie, ob node_modules wie erwartet entsteht.

Nach der Migration können Sie die alte package-lock.json oder yarn.lock löschen. Trotzdem macht es den Rückweg einfacher, beide Lockdateien eine Zeit lang parallel zu behalten, bis das ganze Team umgestiegen ist.

Worauf Sollten Sie Beim Umstieg Achten?

Das häufigste Problem beim Umstieg ist die bereits beschriebene Phantomabhängigkeit: Ein Projekt kann plötzlich die Meldung "Modul nicht gefunden" ausgeben. In diesem Fall fügen Sie das fehlende Paket also einfach direkt in der package.json hinzu.

Zweitens zählt, wo der Speicher liegt. Liegt der Speicher nicht auf demselben Laufwerk wie das Projekt, muss das Werkzeug Dateien kopieren statt verknüpfen, und der erwartete Speichervorteil schrumpft. Deshalb lohnt es sich, die Laufwerkseinstellung früh zu prüfen.

Drittens prüfen Sie den Caching Schritt in Ihrer CI/CD Pipeline. Cachen Sie den Speicher nicht, lädt jeder Build Pakete erneut herunter. Nutzen Sie dagegen pm2 für Ihre Node.js Anwendung auf einem Server, empfehlen wir, diese Einstellung früh in derselben Umgebung zu klären.

Für Welche Projekte Lohnt Sich pnpm am Meisten?

Teams, die viele Node.js Projekte auf derselben Maschine oder demselben CI Server betreiben, bemerken den Speichervorteil zuerst. Teams, die ein Monorepo aufbauen, erhalten über Workspaces ebenfalls eine fest eingebaute Lösung.

Für ein kleines, einmaliges Skript ist ein Werkzeugwechsel meist nicht nötig; Ihre vorhandene npm Einrichtung reicht dann völlig aus. Richtet Ihr Team eine individuelle Projektumgebung ein und sucht dabei externe Unterstützung, lohnt ein Blick auf unsere individuelle Softwareentwicklung.

Für Teams, die mit TypeScript arbeiten, hängt die Wahl des Paketmanagers zusätzlich von der Kompatibilität mit den eigenen Build Werkzeugen ab. Diesen Vergleich behandeln wir separat in unserem Ratgeber zu TypeScript und JavaScript.

Agenturen und Beratungen, die viele Kundenprojekte gleichzeitig betreuen, profitieren ebenfalls deutlich. Die meisten Abhängigkeiten überlappen sich zwischen Projekten, selbst wenn jeder Kunde einen eigenen Ordner hat, sodass ein gemeinsamer Speicher viele Dopplungen entfernt. Ein freiberuflicher Entwickler mit Dutzenden alten Projekten auf einem Laptop kann einen ähnlichen Gewinn allein erleben.

Auch Studierende, die mit kleinen Experimenten lernen, profitieren von diesem Umstieg. Sobald man die Logik des Speichers verstanden hat, fällt es leichter zu begreifen, wie Abhängigkeitsverwaltung im Hintergrund funktioniert. Dieses Verständnis hilft später unabhängig davon, welches Werkzeug man einsetzt.

Auch kleine interne Tools und Automatisierungsskripte, die ein Team über Jahre pflegt, profitieren von der klareren Abhängigkeitsstruktur. Zudem wird eine Übergabe an neue Kolleginnen und Kollegen einfacher, wenn die package.json genau die Pakete nennt, die der Code tatsächlich braucht. Ein Wechsel der zuständigen Person verläuft so deutlich reibungsloser, weil niemand mühsam herausfinden muss, welche Abhängigkeit der Code wirklich braucht.

Hat pnpm auch Nachteile?

Die häufigste Beschwerde betrifft ältere Werkzeuge, die mit einem symlinkbasierten node_modules schlecht zurechtkommen. Sie erwarten einen flachen Ordner und melden einen Fehler, wenn sie keinen finden.

In diesem Fall stellen Sie nodeLinker auf hoisted um und erhalten ein npm ähnliches, flaches Layout. Diese Entscheidung bedeutet aber auch, einen Teil der strengen Abhängigkeitsprüfung aufzugeben. Jede Einstellung bringt einen eigenen Kompromiss mit sich.

Außerdem muss das ganze Team auf denselben Paketmanager umsteigen. Nutzt eine Person npm und eine andere dieses Werkzeug, können Lockdateien in Konflikt geraten. Deshalb empfehlen wir, diese Entscheidung gemeinsam im Team zu treffen.

Community Ressourcen und Tutorials von Dritten konzentrieren sich noch stärker auf npm, weil es die größere Nutzerbasis hat. Deshalb dauert die Suche nach einer Lösung für eine seltene Fehlermeldung manchmal etwas länger. Wer die offizielle Dokumentation und Community Foren regelmäßig verfolgt, gleicht diesen Abstand größtenteils aus, und mindestens eine Person im Team mit diesem Wissen hilft dem ganzen Rest.

Wie Stark Unterscheiden Sich die Befehle von npm?

Im Alltag funktionieren Befehle wie install, add Paketname und run Skriptname weitgehend mit derselben Logik wie ihre npm Gegenstücke. Weil die Befehlsnamen kürzer sind, finden manche Teams dieses Werkzeug praktischer.

Der Unterschied zeigt sich im Hintergrund: npm install schreibt jedes Paket neu, während der install Befehl dieses Werkzeugs mit der Datei im Speicher verknüpft. Für den Anwender bleibt der sichtbare Unterschied meist auf Zeit und Speicherbedarf beschränkt.

Skripte ausführen, Pakete veröffentlichen und Versionen festschreiben folgen im Alltag fast derselben Befehlssyntax. Deshalb gibt es für ein Team nur sehr wenig neue Syntax zu lernen.

Welche Punkte Werden bei pnpm Häufig Verwechselt?

Ein Irrglaube besagt, dieses Werkzeug "komprimiere" Pakete oder nutze ein anderes Paketformat. Tatsächlich bezieht es Pakete aus derselben npm Registry. Anders ist nur, wie diese Pakete auf der Platte gespeichert und verknüpft werden.

Eine weitere Verwechslung ist die Annahme, Symlinks würden ein Sicherheitsrisiko schaffen. Die Standardstruktur bewirkt tatsächlich das Gegenteil: Sie macht sichtbarer, welches Paket wirklich deklariert ist, und verringert dadurch versehentliche Nutzung von Abhängigkeiten.

Manche Teams nehmen außerdem an, dieses Werkzeug zähle nur für große Monorepos. Workspaces bieten dort einen klaren Vorteil, doch Speichervorteil und strenge Abhängigkeitsprüfung gelten genauso für ein einzelnes, kleines Projekt.

Welche Flags Nutzen Sie auf der Kommandozeile am Häufigsten?

Das Flag -w führt einen Befehl innerhalb eines Monorepos gegen den Workspace Stamm aus, unabhängig davon, in welchem Paketordner Sie sich gerade befinden. So fügen Sie eine Abhängigkeit auf Stammebene hinzu, ohne vorher den Ordner zu wechseln.

Das Flag --filter zielt auf ein bestimmtes Paket oder eine Gruppe von Paketen innerhalb eines Workspace. In einem großen Monorepo verschwendet es Zeit, jeden Befehl gegen den gesamten Workspace auszuführen. Deshalb spart das Filtern auf die betroffenen Pakete echte Zeit.

Sie können diese Flags in Ihre package.json Skripte einbauen, damit Teammitglieder sich den langen Befehl nicht merken müssen. Ein kurzer Skriptname erledigt denselben Zweck.

Kombinieren Sie --filter mit --recursive, wählt der Befehl zuerst die Zielpakete aus und wiederholt dieselbe Aktion dann in jedem einzelnen. Einmal richtig eingerichtet, aktualisieren Sie mit einem einzigen Befehl jedes verwandte Paket in einem großen Monorepo, und das Team vermeidet manuelle, fehleranfällige Schritte.

Fazit: Ist pnpm die Richtige Wahl für Ihr Projekt?

Zurück zur Ausgangsfrage, was pnpm ist: Es ist ein Paketmanager, der Festplattenspeicher spart, Abhängigkeiten strenger auflöst und eine fest eingebaute Monorepo Unterstützung mitbringt. Diese drei Eigenschaften liefern vielen Teams einen guten Grund für den Umstieg.

Wie jedes Werkzeug bringt es aber auch Kompromisse mit sich. Kämpfen Ihre älteren Werkzeuge mit Symlinks, oder legt Ihr Team Wert auf Konsistenz in einer einzigen Methode, empfehlen wir, den Umstieg zuerst in einem kleinen Pilotprojekt zu testen.

Richten Sie eine individuelle Projektumgebung ein und brauchen Sie dabei Unterstützung von der Wahl des Paketmanagers bis zum fertigen Deployment, können Sie sich jederzeit gerne an unser erfahrenes Team wenden. Außerdem helfen Ihnen unser Ratgeber zum ERESOLVE Fehler, unser gRPC Ratgeber und unser WSL2 Ratgeber beim Aufbau einer Entwicklungsumgebung.

Interessiert Sie, wie sich Paketarchitektur auf Betriebssystemebene auswirkt, lohnt ein Blick in unseren Ratgeber zum Linux Paketspiegel. Wer auf Apple Silicon Paketinkompatibilität erlebt, findet in unserem Rosetta Ratgeber ebenfalls Hilfe.