Ein Blick unter die Haube: der Rust-Rewrite von pnpm

pnpm 12 ersetzt die TypeScript-Codebasis von pnpm durch eine native Neuimplementierung in Rust. Befehle, Flags, Einstellungen und Lockfile-Format von pnpm 11 bleiben erhalten, sodass die meisten Projekte ohne Änderungen an der Konfiguration upgraden können.

Wenn Sie pnpm in einem Monorepo und auf einer stark ausgelasteten CI-Flotte einsetzen, haben Sie die Schlagzeilen mit „90 % schneller“ vermutlich schon gesehen und sich gefragt, wo der Haken ist. Eine neue Hauptversion des Tools, das Ihr Lockfile schreibt, verdient eine genauere Prüfung als ein Benchmark-Diagramm.

Dieser Artikel erklärt, warum ein JavaScript-Paketmanager überhaupt langsam ist, was die Rust-Engine verändert hat und welchen Preis das hat, wer welche Zahlen gemessen hat und welche Verhaltensänderungen Ihre Pipeline betreffen können.

Die Vorgabe: dasselbe pnpm, eine andere Engine

pnpm 12 wurde so entwickelt, dass sich das Upgrade nicht wie eine Migration anfühlt. Der Release-Post zu pnpm 12.0 nennt das ausdrücklich als Ziel, und der Kompatibilitätsleitfaden bestätigt, dass pnpm 12 – abgesehen von einer kurzen Liste an Unterschieden – die Befehle, Flags, Einstellungen und das Lockfile-Format von pnpm 11 beibehält. Auch der inhaltsadressierbare Store bleibt bestehen, über den Projekte Paketdateien gemeinsam nutzen, statt sie zu kopieren. InfoQ führt zudem das Layout von node_modules als unverändert auf.

Die meisten Rewrites nutzen die neue Codebasis als Gelegenheit, alte Designentscheidungen zu korrigieren. pnpm hat dagegen Kompatibilität zum Ziel erklärt – so weit, dass laut pnpm die Dokumentation für beide Versionen gilt. An der Oberfläche hat sich fast nichts geändert. Die eigentliche Arbeit bestand darin, alles darunter zu ersetzen.

Warum ist ein JavaScript-Paketmanager langsam?

Ein in JavaScript geschriebener Paketmanager zahlt bei jeder großen Installation zwei Kosten: Er startet bei jedem Aufruf die Node.js-Runtime, und er schleust Tausende Dateisystemoperationen durch eine einzige JavaScript-Runtime.

Eine Installation durchläuft grob folgende Phasen:

1. Paketmetadaten aus der Registry abrufen.
2. Den Abhängigkeitsgraphen auflösen.
3. Tarballs herunterladen.
4. Sie in den Store entpacken.
5. Pakete in node_modules verlinken.

Die ersten Kosten sind fix. Bevor pnpm 11 irgendeine echte Arbeit verrichtete, musste Node.js starten. pnpm 12 wird als native Binaries veröffentlicht, mit einem @pnpm/exe.<platform>-<arch>-Paket pro Plattform. Die Dokumentation zu self-update bestätigt, dass vorher nichts Node.js startet – diese Startkosten entfallen also.

Die zweiten Kosten wachsen mit dem Arbeitsumfang. Die Phasen 4 und 5 umfassen das Entpacken von Tarballs und das Anlegen von Hardlinks für Tausende Dateien, und jede dieser Operationen läuft durch die JavaScript-Runtime.

Das Prinzip lässt sich auf jedes Tool übertragen: Das Entfernen eines festen Overheads bringt am meisten, wenn sonst kaum Arbeit anfällt. Hat eine Installation fast nichts zu tun, macht der Start den Großteil der tatsächlichen Laufzeit aus. Müssen dagegen Hunderte Megabyte heruntergeladen werden, fällt der Start kaum ins Gewicht.

Wie viel schneller ist pnpm 12?

Die Geschwindigkeitsgewinne von pnpm 12 sind real, aber ungleich verteilt: Eine warme, wiederholte Installation sinkt von 563 ms auf 18 ms, eine saubere Installation hingegen nur von 8,4 s auf 4,4 s. Die Zahlen stammen aus zwei getrennten Messreihen mit unterschiedlichen Baselines. Fassen Sie sie nicht zu einer einzigen Zahl zusammen.

Die pnpm-Werte beziehen sich auf das Projekt alotta-files auf der pnpm-Benchmark-Seite und vergleichen pnpm 11.27.1 mit pnpm 12.7.0. Die Seite wird regelmäßig neu ausgeführt und zeigt stets die neueste Version jedes Tools – rechnen Sie also damit, dass sich diese Zahlen ändern. Der Abstand zwischen den beiden pnpm-Zeilen ist der vorherige Abschnitt in der Praxis: Die warme Installation verbessert sich etwa um das 30-Fache, höchstwahrscheinlich weil Fixkosten wie der Start einen großen Teil ihrer Laufzeit ausmachten. Die saubere Installation verbessert sich nur etwa um das 1,9-Fache, weil Netzwerkübertragung und das Entpacken der Tarballs den Großteil der Zeit beanspruchen – unabhängig davon, in welcher Sprache die Engine geschrieben ist.

Die eigenen Messungen von Vercel zeigen dasselbe Muster. Mit bereits vorhandenem node_modules, warmem Store und deaktivierten Skripten sanken die Installationszeiten von 1,476 s auf 142 ms. Eine vollständig kalte Installation mit aktivierten Lifecycle-Skripten ging von 9,850 s auf 3,472 s zurück. Jeder Median basiert auf 20 Durchläufen pro Version auf einer einzelnen Linux-Maschine in einem Turborepo-Workspace mit 21 Projekten.

Der native Build von pnpm 12 hat seinen Preis. Vercel beziffert den Corepack-Download von pnpm 12 auf 47,3 MB gegenüber 17,5 MB bei pnpm 10.28.0 und führt den langsameren ungecachten Start auf diesen größeren Download zurück. CI-Runner, die Corepack nicht cachen, zahlen diesen Preis wahrscheinlich bei jedem Job.

Ein davon unabhängiger Gewinn ist die deterministische Behandlung von Zyklen, die zusammen mit der Engine ausgeliefert wird. Der Kompatibilitätsleitfaden von pnpm schreibt rund 25 % geringeren Speicherverbrauch und eine 2- bis 3-mal schnellere Peer-Auflösung in zyklenreichen Workspaces dieser Änderung zu – und nicht der Rust-Engine selbst.

Die öffentliche Benchmark-Seite von pnpm vergleicht pnpm 12 inzwischen nur noch mit npm und pnpm 11. Laut InfoQ hat pnpm Bun und Yarn aus dem Vergleich entfernt, nachdem Probleme beim Benchmark-Setup diese Rankings unzuverlässig gemacht hatten.

Warum musste das Lockfile-Format von pnpm identisch bleiben?

Das Lockfile-Format von pnpm 12 musste gleich bleiben, weil ein Formatbruch ein Team mitten im Upgrade spalten würde. Würde pnpm 12 ein neues Format schreiben, müssten alle Laptops und CI-Runner am selben Tag umgestellt werden. Andernfalls würden zwei Lockfile-Dialekte in einem Repository konkurrieren, und jeder Pull Request enthielte Rauschen von der Version, die zuletzt gelaufen ist.

Das unveränderte Format soll einem Team ein schrittweises Upgrade ermöglichen. Es bedeutet nicht, dass sich am Inhalt der Datei niemals etwas ändert. Format und Inhalt sind zwei verschiedene Dinge:

• Bestehende Lockfiles funktionieren weiterhin. Laut Leitfaden lässt pnpm vorhandene Einträge unangetastet, bis etwas eine erneute Auflösung auslöst.
• Eine erneute Auflösung kann Einträge verändern. pnpm 12 hinterlegt Abhängigkeiten von GitHub, GitLab und Bitbucket unter ihrer HTTPS-URL, niemals unter einer SSH-URL. Außerdem trennt pnpm 12 Abhängigkeitszyklen jedes Mal an derselben Stelle auf, was Lockfiles in Workspaces mit vielen Zyklen verkleinert.

Prüfen Sie den Diff Ihrer ersten erneut auflösenden Installation unter pnpm 12 als separaten Commit.

Was bricht beim Upgrade auf pnpm 12?

Wenn ein Upgrade auf pnpm 12 einen CI-Job bricht, ist die wahrscheinlichste Ursache ein Skript, das noch pnpm install --resolution-only aufruft. v12 lehnt dieses Flag ab. Seine Aufgabe, Peer-Dependencies zu melden, übernimmt nun pnpm peers check:

# pnpm 11
pnpm install --resolution-only

# pnpm 12
pnpm peers check

v12 lehnt außerdem pnpm install --frozen-lockfile false ab. Verwenden Sie --no-frozen-lockfile, um den Frozen-Lockfile-Modus zu deaktivieren, und einfach --frozen-lockfile, um ihn zu aktivieren.

Andere Änderungen wirken sich überwiegend auf das Ergebnis aus, drei davon können jedoch auch einen Befehl abbrechen:

Die Release Notes zu v12.0.0 erklären, warum die Workspace-Prüfung wichtig ist. In pnpm 11 führte ein Tippfehler in einer Einstellung wie minimumReleaseAge dazu, dass pnpm den Schlüssel kommentarlos übersprang – die beabsichtigte Regel griff also nie:

# pnpm-workspace.yaml
packages:
  - "apps/*"
minimumReleseAge:   # typo: pnpm 12 reports this key

Der Kompatibilitätsleitfaden listet insgesamt acht Unterschiede auf. Sechs davon ändern ein Ergebnis, zwei lehnen Kommandozeilensyntax ab, die pnpm 11 akzeptiert hat: --resolution-only und --frozen-lockfile false. Die obige Tabelle deckt nicht alle davon ab. Sie lässt aus, wie pnpm 12 Paketmanager-Namen wie yarn in pnpm add behandelt, und die Zeilen zu Workspace-Schlüsseln und sudo stammen aus den Release Notes, nicht aus dem Leitfaden. Lesen Sie vor dem Upgrade den vollständigen Leitfaden.

Sollten Sie auf pnpm 12 upgraden?

In der Regel ja – und das Upgrade verläuft unspektakulär. Genau das war das Designziel. Ab pnpm 11.10 oder neuer führen Sie aus:

pnpm self-update

In einem Projekt, das pnpm über packageManager pinnt, erhöht self-update lediglich die Version in diesem Feld, statt pnpm global zu installieren. pnpm lädt die neue Version dann beim nächsten Befehlsaufruf herunter. Committen Sie die Änderung, damit CI dieselbe Version verwendet:

{
  "packageManager": "pnpm@12.8.1"
}

Verwenden Sie das neueste 12.x-Release. Wenn Ihre Installation von weniger gängigen Features wie pnpm deploy oder bestimmten Linker-Modi abhängt, testen Sie das Upgrade zunächst auf einem Branch. Teams, die noch npm verwenden, können nachlesen, ob sich der Umstieg von npm auf pnpm lohnt, bevor sie beide Umstellungen gleichzeitig angehen.

Fazit

pnpm 12 hat die Teile beibehalten, die Sie täglich nutzen – darunter die Befehle, das Lockfile-Format und das Store-Modell – und die Engine dahinter neu aufgebaut. Der Rewrite hat sich ausgezahlt, weil zwei Kostenfaktoren die JavaScript-Version ausgebremst haben: der Node.js-Start bei jedem Aufruf und die Datei-I/O, die durch eine einzige Runtime geschleust wurde. Durchsuchen Sie vor dem Upgrade Ihre CI-Konfiguration nach --resolution-only und --frozen-lockfile false, prüfen Sie, ob private Git-Abhängigkeiten per SSH eingebunden sind, und committen Sie das erste neu aufgelöste Lockfile separat, damit Sie den Diff prüfen können.

FAQs

Benötigt pnpm 12 eine Node.js-Installation, um zu laufen?

Nein. Nach der Installation läuft pnpm 12 als natives Programm, Node.js wird also nicht benötigt. Auch das eigenständige Installationsskript kommt ohne Node.js aus, selbst während der Installation. Die einzige Ausnahme ist die Installation von pnpm 12 über npm: Hier benötigt der Installer Node.js 22.13 oder neuer. Gibt es für Ihre Plattform kein vorkompiliertes pnpm-12-Binary, empfiehlt die pnpm-Dokumentation, stattdessen das JavaScript-basierte pnpm 11 zu verwenden.

Wie kann ich in pnpm 12 weiterhin SSH für private Git-Abhängigkeiten nutzen?

pnpm 12 ruft Abhängigkeiten von GitHub, GitLab und Bitbucket über die jeweilige HTTPS-URL des Hosts ab. Um weiterhin SSH zu verwenden, richten Sie ein Git-URL-Rewriting ein, zum Beispiel mit git config --global url.'git@github.com:'.insteadOf https://github.com/. pnpm ruft intern git auf, daher gilt diese Regel für jeden Git-Befehl, den pnpm ausführt. Hosts, die pnpm nicht erkennt, sowie URLs mit Zugangsdaten bleiben exakt so, wie Sie sie geschrieben haben – SSH eingeschlossen.

Warum schlägt pnpm 12 bei einer unbekannten Einstellung in pnpm-workspace.yaml fehl?

Ein Fehler tritt nur auf, wenn das Projekt eine pnpm-Version pinnt und die laufende pnpm-Version diesem Pin entspricht. In diesem Fall behandelt pnpm den unbekannten Schlüssel als Fehler und bricht mit ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS ab. Ohne passenden Pin erhalten Sie eine Warnung, und der Befehl läuft weiter. Sieht der Schlüssel nach einem Tippfehler aus, nennt pnpm die vermutlich gemeinte Einstellung. Die pnpm-config-Befehle funktionieren auch mit einer Datei, die einen fehlerhaften Schlüssel enthält, sodass Sie ihn damit finden und korrigieren können.

Welche pnpm-12-Befehle schlagen fehl, wenn sie mit sudo ausgeführt werden?

Unter sudo brechen pnpm setup, pnpm self-update und alle Befehle, die die globale Installation ändern – etwa pnpm add --global – mit ERR_PNPM_SUDO_NOT_SUPPORTED ab. Frühere Versionen schrieben stattdessen stillschweigend in das Home-Verzeichnis von root. Globale Pakete und Einstellungen liegen in Ihrem eigenen Home-Verzeichnis, daher benötigt keiner dieser Befehle Root-Rechte. Rein lesende Befehle wie pnpm bin --global funktionieren unter sudo weiterhin.