Was bunx ist und wann man es verwendet

bunx ist Buns Package-Runner und ein Alias für bun x; es lädt ein Paket-Binary von npm herunter und führt es aus, ohne eine globale Installation zu erfordern – dieselbe Aufgabe, die npx und yarn dlx übernehmen.

Wer schon einmal darauf gewartet hat, dass npx einen Scaffold-Befehl startet, den man dutzende Male täglich ausführt, kennt genau die Verzögerung, die bunx beseitigen soll. Wer täglich npx create-next-app oder npx shadcn@latest eintippt, findet in bunx einen nahezu vollständigen Ersatz, sobald Bun auf dem Rechner installiert ist – mit einer Besonderheit beim Laufzeitverhalten (--bun) und einem echten Fallstrick (Tools, die den Literal-String npx fest verdrahtet haben), die man vor dem Umstieg verstehen sollte.

Dieser Artikel vermittelt das nötige Grundverständnis: Was bunx ist, wie es Pakete auflöst, warum es schneller startet als npx, was das Flag --bun tatsächlich bewirkt und eine Entscheidungsregel, wann man es einsetzen sollte.

Was ist bunx?

bunx führt eine ausführbare Datei aus einem npm-Paket aus, ohne es global zu installieren, und wird automatisch mit Bun mitgeliefert. Die Dokumentation bestätigt, dass bunx ein Alias für bun x ist und bei der Installation von Bun automatisch eingerichtet wird. Es ist Buns Äquivalent zu npx oder yarn dlx.

Die Aufruf-Syntax ist identisch mit npx:

# npx
npx create-next-app@latest my-app

# bunx
bunx create-next-app@latest my-app

Pakete deklarieren ihre Binaries im Feld "bin" der package.json; bunx <paket> findet dieses Binary und führt es aus. Die Versionsfixierung funktioniert genauso wie bei npx – einfach @version an den Paketnamen anhängen:

bunx uglify-js@3.14.0 app.js
bunx shadcn@latest add button

Wenn der Name der ausführbaren Datei vom Paketnamen abweicht, gibt man das Paket mit -p/--package explizit an und nennt anschließend die ausführbare Datei:

bunx -p @angular/cli ng new my-app

Wie löst bunx ein Paket auf?

bunx prüft zunächst, ob eine lokal installierte Kopie des Pakets vorhanden ist, greift dann auf eine automatische Installation von npm zurück und speichert das Installierte in Buns globalem Cache zur Wiederverwendung. Dieses Verhalten ist dokumentiert: „Wie bei npx prüft bunx zunächst, ob ein lokal installiertes Paket vorhanden ist, und greift dann auf eine automatische Installation von npm zurück.” Aufgelöste Pakete landen in Buns globalem Cache, sodass spätere Aufrufe den Download überspringen.

Eine wichtige Richtigstellung: Modernes npx (npm v7+, also npm exec) lädt bei jedem Aufruf nicht herunter und verwirft das Ergebnis anschließend. Es pflegt ebenfalls einen persistenten, benutzerspezifischen Cache und verwendet Pakete bei wiederholten Aufrufen erneut. Der eigentliche Unterschied liegt also nicht darin, dass „npx verwirft und bunx behält”; beide cachen. Der echte Differenzierungsfaktor ist der Speicherort des Caches (Buns eigener globaler Store) sowie der Laufzeit-Overhead vom Aufruf bis zur Ausführung.

Warum bunx schneller ist als npx

bunx startet schneller, weil es auf Buns Laufzeitumgebung läuft, die auf JavaScriptCore (Safaris Engine) aufbaut, anstatt Node hochzufahren – der feste Startaufwand des Package-Runners ist damit geringer. Buns Team beziffert den Vorteil konkret: Die Einführung von bunx wurde damit beworben, eine ausführbare Datei von npm zu installieren und auszuführen – 100-mal schneller als npx, eine Zahl, die die Dokumentation explizit auf lokal installierte Pakete bezieht.

Diese Zahl sollte man als Buns veröffentlichte Angabe für den warmen, bereits installierten Fall betrachten – nicht als universellen Benchmark. Die Aussage zum Startverhalten lässt sich jedoch verallgemeinern: Bei einem Kaltstart-CLI-Aufruf (dem Vorgang, den man beim Scaffolding von Projekten dutzende Male täglich ausführt) macht sich Buns geringerer Prozessstart-Overhead zeitlich bemerkbar. Bei einer Erstinstallation, die das Netzwerk beansprucht, zahlen beide Tools die Download-Kosten, und jeder Geschwindigkeitsunterschied reduziert sich auf den Installations-Durchsatz plus das Startdelta – weit entfernt von einem 100-fachen Vorsprung.

Wer eine verlässliche Zahl möchte, sollte selbst messen und dabei Kaltstart- von Warmstart-Läufen trennen:

# Warm-Cache (beide bereits aufgelöst) vs. kalt — messen, nicht annehmen
hyperfine 'npx cowsay hi' 'bunx cowsay hi'

Das Flag —bun

Das Flag --bun zwingt ein CLI wie Vite, Next oder Prisma dazu, auf der Bun-Laufzeitumgebung statt auf Node ausgeführt zu werden, und überschreibt dabei den Shebang #!/usr/bin/env node, mit dem das Tool normalerweise ausgeliefert wird. Standardmäßig respektiert Bun diesen Shebang und startet einen node-Prozess, um die Datei auszuführen; --bun weist es an, stattdessen Buns Laufzeitumgebung zu verwenden:

bunx --bun vite dev

Das Flag ist positionsabhängig. Es muss vor dem Namen der ausführbaren Datei stehen. Alles, was nach dem Namen folgt, wird direkt als eigenes Argument an das Tool weitergereicht:

bunx --bun my-cli   # korrekt — führt my-cli auf Bun aus
bunx my-cli --bun   # falsch — übergibt --bun an my-cli

--bun sollte man verwenden, wenn man das Tool tatsächlich auf Bun ausführen möchte – um von Buns schnellerem Start oder der nativen TypeScript-Unterstützung zu profitieren. Ohne das Flag (Standardverhalten) bleibt man auf der sicheren Seite, wenn ein Tool auf Node-spezifisches Verhalten angewiesen ist; manche Build-Tools und CLIs setzen Node-Interna voraus, und das Erzwingen von Buns Laufzeitumgebung kann Kompatibilitätsprobleme aufdecken. In der Praxis ist ein häufiges Fehlerbild ein CLI, das unter bunx toolname problemlos funktioniert, aber Fehler wirft, sobald --bun die Laufzeitumgebung austauscht. Die Lösung besteht meist darin, --bun wegzulassen und den Node-Shebang zu respektieren.

Wann man bunx verwendet (und wann man bei npx bleibt)

Entscheidungsregel: bunx für einmalige Scaffolding-Vorgänge und CLI-Tools verwenden (bunx create-next-app my-app, bunx prisma migrate, bunx prettier foo.js) und nur dann bei npx bleiben, wenn etwas den Literal-String npx fest verdrahtet hat oder auf Buns Laufzeitumgebung nicht funktioniert.

Der eigentliche Fallstrick ist Tooling, das npx namentlich aufruft. Ein Shell-Alias wie alias npx=bunx funktioniert, wenn man Befehle interaktiv eingibt, aber Shell-Aliases existieren nur in interaktiven Shells: Für nicht-interaktive Prozesse sind sie unsichtbar. Ein Tool, das npx intern aufruft (etwa uv run, das es intern verwendet), wird den Alias überhaupt nicht sehen.

Die Lösung besteht darin, eine echte ausführbare Datei namens npx im PATH abzulegen, sodass jeder Prozess, der npx aufruft, auf das Shim umgeleitet wird. Der htdocs-Workaround besteht aus drei Zeilen:

mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec bunx "$@"\n' > ~/.local/bin/npx
chmod +x ~/.local/bin/npx

~/.local/bin muss dabei früh im PATH stehen. Da es sich um eine echte Datei auf dem Datenträger handelt und nicht um einen Shell-Alias, wird sie auch von nicht-interaktiven Prozessen aufgelöst. Wer einen Fallback möchte, der nur dann über Bun läuft, wenn es installiert ist, findet in einer bedingten Wrapper-Funktion mit einem --real-Escape-Hatch, wie von nrjdalal gezeigt, die ausgefeiltere Variante desselben Ansatzes.

Fazit

bunx lässt sich als npx auf einer schnelleren Laufzeitumgebung betrachten: gleiche Auflösungsreihenfolge, gleiche Syntax zur Versionsfixierung, gleiche Befehlsstruktur – mit geringerem Startaufwand und Paketen, die in Buns eigenem Store gecacht werden. Das Flag --bun sollte man nur dann hinzufügen, wenn das Tool selbst auf Bun laufen soll; es muss vor dem Namen der ausführbaren Datei stehen. Für die wenigen Tools, die den Literal-Befehl voraussetzen, legt man ein echtes npx-Shim im PATH ab. Bun installieren, beim nächsten Scaffold-Vorgang ein npx durch bunx ersetzen und den Unterschied selbst messen.

Häufig gestellte Fragen

Ist bunx ein vollständiger Ersatz für npx?

bunx ist ein nahezu vollständiger Ersatz für npx: Es teilt dieselbe Befehlsstruktur, dieselbe Syntax zur Versionsfixierung mit dem @version-Suffix und dieselbe local-first-Auflösungsreihenfolge. Die einzige Ausnahme sind Tools oder Skripte, die den Literal-String npx intern aufrufen und bunx nicht erkennen, sofern keine echte ausführbare Datei namens npx im PATH abgelegt wurde. In diesen Fällen wird bunx nicht automatisch als Ersatz herangezogen.

Funktioniert bunx ohne separate Installation von Bun?

Nein, bunx setzt Bun voraus. bunx ist ein Alias für den Befehl bun x und wird automatisch bei der Installation von Bun eingerichtet; es gibt kein eigenständiges bunx-Paket. Sobald Bun auf dem Rechner installiert ist, steht bunx ohne weiteren Einrichtungsaufwand zur Verfügung. Ist Bun nicht installiert, existiert der Befehl bunx nicht, und man muss auf npx oder einen anderen Package-Runner zurückgreifen.

Was ist der Unterschied zwischen bun x und bunx?

Es gibt keinen funktionalen Unterschied: bunx ist schlicht ein Alias für bun x, sodass beide Befehle identisch ausgeführt werden. Beide rufen Buns Package-Runner auf, um das Binary eines Pakets ohne globale Installation auszuführen. Welche Schreibweise man bevorzugt, bleibt einem selbst überlassen. bunx existiert hauptsächlich als kürzere, npx-vertraute Form, die Entwickler, die von npm kommen, sofort wiedererkennen.

Warum bricht bunx --bun manche CLIs, die ohne dieses Flag problemlos laufen?

Weil --bun das CLI zwingt, auf Buns Laufzeitumgebung statt auf Node ausgeführt zu werden, und dabei den Node-Shebang überschreibt, mit dem das Tool ausgeliefert wird. Manche Build-Tools und CLIs sind auf Node-spezifische Interna angewiesen, sodass der Austausch der Laufzeitumgebung Kompatibilitätsprobleme aufdeckt. Ein Tool, das unter bunx toolname funktioniert, kann nach dem Hinzufügen von --bun Fehler werfen. Die Lösung besteht darin, --bun wegzulassen und das Tool wie vom Shebang vorgesehen auf Node laufen zu lassen.