import Install from "/snippets/cli/install.mdx";

Grundlegende Verwendung

bun install react
bun install react@19.1.1 # bestimmte Version
bun install react@latest # bestimmtes Tag

Die bun-CLI enthält einen mit Node.js kompatiblen Paketmanager, der als deutlich schnellere Alternative zu npm, yarn und pnpm entwickelt wurde. Es ist ein eigenständiges Tool, das in bestehenden Node.js-Projekten funktioniert; wenn Ihr Projekt eine package.json hat, kann bun install Ihnen helfen, Ihren Workflow zu beschleunigen.

NOTE

⚡️ 25x schneller — Wechseln Sie von npm install zu bun install in jedem Node.js-Projekt, um Ihre Installationen bis zu 25x schneller zu machen.

Für Linux-Benutzer

Die empfohlene minimale Linux-Kernel-Version ist 5.6. Wenn Sie Linux-Kernel 5.1 - 5.5 verwenden, funktioniert bun install, aber HTTP-Anfragen sind aufgrund fehlender Unterstützung für io_uring's connect()-Operation langsam.

Wenn Sie Ubuntu 20.04 verwenden, installieren Sie einen neueren Kernel:

# Wenn dies eine Version >= 5.6 zurückgibt, müssen Sie nichts tun
uname -r

# Installieren Sie den offiziellen Ubuntu-Hardware-Enablement-Kernel
sudo apt install --install-recommends linux-generic-hwe-20.04

Um alle Abhängigkeiten eines Projekts zu installieren:

bun install

Die Ausführung von bun install führt Folgendes aus:

• Installiert alle dependencies, devDependencies und optionalDependencies. Bun installiert standardmäßig peerDependencies.
• Führt die {pre|post}install- und {pre|post}prepare-Skripte Ihres Projekts zum geeigneten Zeitpunkt aus. Aus Sicherheitsgründen führt Bun Lifecycle-Skripte von installierten Abhängigkeiten nicht aus.
• Schreibt eine bun.lock-Lockfile in das Projektverzeichnis.

---

Protokollierung

Um die Ausführlichkeit der Protokollierung zu ändern:

bun install --verbose # Debug-Protokollierung
bun install --silent  # keine Protokollierung

---

Lifecycle-Skripte

Im Gegensatz zu anderen npm-Clients führt Bun keine beliebigen Lifecycle-Skripte wie postinstall für installierte Abhängigkeiten aus. Das Ausführen beliebiger Skripte stellt ein potenzielles Sicherheitsrisiko dar.

Um Bun mitzuteilen, dass es Lifecycle-Skripte für ein bestimmtes Paket zulassen soll, fügen Sie das Paket zu trustedDependencies in Ihrer package.json hinzu.

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}

Installieren Sie dann das Paket neu. Bun liest dieses Feld und führt Lifecycle-Skripte für my-trusted-package aus.

Lifecycle-Skripte werden während der Installation parallel ausgeführt. Um die maximale Anzahl gleichzeitiger Skripte anzupassen, verwenden Sie das --concurrent-scripts-Flag. Der Standardwert ist das Zweifache der gemeldeten CPU-Anzahl oder GOMAXPROCS.

bun install --concurrent-scripts 5

Bun optimiert automatisch postinstall-Skripte für beliebte Pakete (wie esbuild, sharp usw.), indem es ermittelt, welche Skripte ausgeführt werden müssen. Um diese Optimierungen zu deaktivieren:

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

Workspaces

Bun unterstützt "workspaces" in package.json. Vollständige Dokumentation finden Sie unter Paketmanager > Workspaces.

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

---

Installation von Abhängigkeiten für bestimmte Pakete

In einem Monorepo können Sie die Abhängigkeiten für eine Teilmenge von Paketen mit dem --filter-Flag installieren.

# Installiert Abhängigkeiten für alle Workspaces außer `pkg-c`
bun install --filter '!pkg-c'

# Installiert Abhängigkeiten nur für `pkg-a` in `./packages/pkg-a`
bun install --filter './packages/pkg-a'

Weitere Informationen zum Filtern mit bun install finden Sie unter Paketmanager > Filtern

---

Overrides und Resolutions

Bun unterstützt "overrides" von npm und "resolutions" von Yarn in package.json. Dies sind Mechanismen zur Angabe eines Versionsbereichs für Metadependencies — die Abhängigkeiten Ihrer Abhängigkeiten. Vollständige Dokumentation finden Sie unter Paketmanager > Overrides und Resolutions.

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

---

Globale Pakete

Um ein Paket global zu installieren, verwenden Sie das -g/--global-Flag. Typischerweise wird dies für die Installation von Befehlszeilen-Tools verwendet.

bun install --global cowsay # oder `bun install -g cowsay`
cowsay "Bun!"

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

---

Produktionsmodus

Um im Produktionsmodus zu installieren (d.h. ohne devDependencies oder optionalDependencies):

bun install --production

Für reproduzierbare Installationen verwenden Sie --frozen-lockfile. Dies installiert die exakten Versionen jedes in der Lockfile angegebenen Pakets. Wenn Ihre package.json nicht mit bun.lock übereinstimmt, beendet Bun mit einem Fehler. Die Lockfile wird nicht aktualisiert.

bun install --frozen-lockfile

Weitere Informationen zu Buns Lockfile bun.lock finden Sie unter Paketmanager > Lockfile.

---

Auslassen von Abhängigkeiten

Um dev-, peer- oder optionale Abhängigkeiten auszulassen, verwenden Sie das --omit-Flag.

# Schließt "devDependencies" von der Installation aus. Dies gilt für das
# root-Paket und Workspaces, falls vorhanden. Transitive Abhängigkeiten haben
# keine "devDependencies".
bun install --omit dev

# Installiert nur Abhängigkeiten aus "dependencies"
bun install --omit=dev --omit=peer --omit=optional

---

Trockenlauf

Um einen Trockenlauf durchzuführen (d.h. nichts tatsächlich zu installieren):

bun install --dry-run

---

Nicht-npm-Abhängigkeiten

Bun unterstützt die Installation von Abhängigkeiten von Git, GitHub und lokalen oder remote gehosteten Tarballs. Vollständige Dokumentation finden Sie unter Paketmanager > Git-, GitHub- und Tarball-Abhängigkeiten.

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

---

Installationsstrategien

Bun unterstützt zwei Paketinstallationsstrategien, die bestimmen, wie Abhängigkeiten in node_modules organisiert werden:

Gehoisste Installationen

Der traditionelle npm/Yarn-Ansatz, der Abhängigkeiten in ein gemeinsames node_modules-Verzeichnis glättet:

bun install --linker hoisted

Isolierte Installationen

Ein pnpm-ähnlicher Ansatz, der strikte Abhängigkeitsisolation erstellt, um Phantom-Abhängigkeiten zu verhindern:

bun install --linker isolated

Isolierte Installationen erstellen einen zentralen Paketspeicher in node_modules/.bun/ mit Symlinks im node_modules auf oberster Ebene. Dies stellt sicher, dass Pakete nur auf ihre deklarierten Abhängigkeiten zugreifen können.

Standardstrategie

Die Standard-Linker-Strategie hängt davon ab, ob Sie neu beginnen oder ein bestehendes Projekt haben:

• Neue Workspaces/Monorepos: isolated (verhindert Phantom-Abhängigkeiten)
• Neue Einzelpaket-Projekte: hoisted (traditionelles npm-Verhalten)
• Bestehende Projekte (vor v1.3.2 erstellt): hoisted (erhält Abwärtskompatibilität)

Der Standardwert wird durch ein configVersion-Feld in Ihrer Lockfile gesteuert. Eine detaillierte Erklärung finden Sie unter Paketmanager > Isolierte Installationen.

---

Mindestalter von Releases

Um sich vor Supply-Chain-Angriffen zu schützen, bei denen bösartige Pakete schnell veröffentlicht werden, können Sie eine Mindestalter-Anforderung für npm-Pakete konfigurieren. Paketversionen, die kürzer als der angegebene Schwellenwert (in Sekunden) veröffentlicht wurden, werden während der Installation herausgefiltert.

# Installiert nur Paketversionen, die vor mindestens 3 Tagen veröffentlicht wurden
bun add @types/bun --minimum-release-age 259200 # Sekunden

Sie können dies auch in bunfig.toml konfigurieren:

[install]
# Installiert nur Paketversionen, die vor mindestens 3 Tagen veröffentlicht wurden
minimumReleaseAge = 259200 # Sekunden

# Schließt vertrauenswürdige Pakete von der Altersprüfung aus
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Wenn der Mindestalter-Filter aktiv ist:

• Betrifft nur neue Paketauflösung - bestehende Pakete in bun.lock bleiben unverändert
• Alle Abhängigkeiten (direkt und transitiv) werden gefiltert, um die Alter-Anforderung bei der Auflösung zu erfüllen
• Wenn Versionen durch den Altersfilter blockiert werden, erkennt eine Stabilitätsprüfung schnelle Bugfix-Muster
  • Wenn mehrere Versionen kurz außerhalb Ihres Altersfilters veröffentlicht wurden, erweitert es den Filter, um diese potenziell instabilen Versionen zu überspringen und wählt eine ältere, reifere Version
  • Durchsucht bis zu 7 Tage nach dem Altersfilter, ignoriert jedoch bei schnellen Veröffentlichungen die Stabilitätsprüfung
  • Exakte Versionanfragen (wie package@1.1.1) respektieren weiterhin den Altersfilter, umgehen aber die Stabilitätsprüfung
• Versionen ohne time-Feld werden als bestanden der Altersprüfung behandelt (npm-Registry sollte immer Zeitstempel bereitstellen)

Für fortgeschrittenes Security-Scanning, einschließlich Integration mit Diensten und benutzerdefiniertem Filtering, siehe Paketmanager > Security-Scanner-API.

---

Konfiguration

Konfiguration von bun install mit bunfig.toml

bunfig.toml wird bei bun install, bun remove und bun add in den folgenden Pfaden gesucht:

1. $XDG_CONFIG_HOME/.bunfig.toml oder $HOME/.bunfig.toml
2. ./bunfig.toml

Wenn beide gefunden werden, werden die Ergebnisse zusammengeführt.

Die Konfiguration mit bunfig.toml ist optional. Bun versucht im Allgemeinen, null Konfiguration zu sein, aber das ist nicht immer möglich. Das Standardverhalten von bun install kann in bunfig.toml konfiguriert werden. Die Standardwerte sind unten gezeigt.

[install]

# ob optionalDependencies installiert werden sollen
optional = true

# ob devDependencies installiert werden sollen
dev = true

# ob peerDependencies installiert werden sollen
peer = true

# entspricht dem `--production`-Flag
production = false

# entspricht dem `--save-text-lockfile`-Flag
saveTextLockfile = false

# entspricht dem `--frozen-lockfile`-Flag
frozenLockfile = false

# entspricht dem `--dry-run`-Flag
dryRun = false

# entspricht dem `--concurrent-scripts`-Flag
concurrentScripts = 16 # (CPU-Anzahl oder GOMAXPROCS) x2

# Installationsstrategie: "hoisted" oder "isolated"
# Standard hängt von lockfile configVersion und workspaces ab:
# - configVersion = 1: "isolated" bei Verwendung von workspaces, sonst "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# Mindestalter-Konfiguration
minimumReleaseAge = 259200 # Sekunden
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Konfiguration mit Umgebungsvariablen

Umgebungsvariablen haben eine höhere Priorität als bunfig.toml.

Name	Beschreibung
BUN_CONFIG_REGISTRY	Legt eine npm-Registry fest (Standard: https://registry.npmjs.org)
BUN_CONFIG_TOKEN	Legt ein Auth-Token fest (derzeit ohne Funktion)
BUN_CONFIG_YARN_LOCKFILE	Speichert eine Yarn v1-artige yarn.lock
BUN_CONFIG_LINK_NATIVE_BINS	Zeigt bin in package.json auf eine plattformspezifische Abhängigkeit
BUN_CONFIG_SKIP_SAVE_LOCKFILE	Speichert keine Lockfile
BUN_CONFIG_SKIP_LOAD_LOCKFILE	Lädt keine Lockfile
BUN_CONFIG_SKIP_INSTALL_PACKAGES	Installiert keine Pakete

Bun versucht immer, die schnellste verfügbare Installationsmethode für die Zielplattform zu verwenden. Unter macOS ist das clonefile und unter Linux ist das hardlink. Sie können mit dem --backend-Flag ändern, welche Installationsmethode verwendet wird. Wenn nicht verfügbar oder bei Fehler, fallen clonefile und hardlink auf eine plattformspezifische Implementierung des Kopierens von Dateien zurück.

Bun speichert installierte Pakete von npm in ~/.bun/install/cache/${name}@${version}. Beachten Sie, dass wenn die Semver-Version ein build- oder pre-Tag hat, es durch einen Hash dieses Werts ersetzt wird. Dies dient dazu, die Wahrscheinlichkeit von Fehlern durch lange Dateipfade zu verringern, erschwert aber leider das Herausfinden, wo ein Paket auf der Festplatte installiert wurde.

Wenn der node_modules-Ordner existiert, prüft Bun vor der Installation, ob der "name" und "version" in package/package.json im erwarteten node_modules-Ordner mit dem erwarteten name und version übereinstimmen. So bestimmt es, ob es installieren soll. Es verwendet einen benutzerdefinierten JSON-Parser, der das Parsen stoppt, sobald er "name" und "version" findet.

Wenn eine bun.lock nicht existiert oder package.json Abhängigkeiten geändert hat, werden Tarballs während der Auflösung heruntergeladen und extrahiert.

Wenn eine bun.lock existiert und package.json sich nicht geändert hat, lädt Bun fehlende Abhängigkeiten lazy herunter. Wenn das Paket mit übereinstimmendem name & version bereits am erwarteten Ort innerhalb von node_modules existiert, versucht Bun nicht, den Tarball herunterzuladen.

CI/CD

Verwenden Sie die offizielle oven-sh/setup-bun-Action, um bun in einer GitHub Actions-Pipeline zu installieren:

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

Für CI/CD-Umgebungen, die reproduzierbare Builds erzwingen möchten, verwenden Sie bun ci, um den Build fehlschlagen zu lassen, wenn die package.json nicht mit der Lockfile synchronisiert ist:

bun ci

Dies entspricht bun install --frozen-lockfile. Es installiert exakte Versionen aus bun.lock und schlägt fehl, wenn package.json nicht mit der Lockfile übereinstimmt. Um bun ci oder bun install --frozen-lockfile zu verwenden, müssen Sie bun.lock in die Versionskontrolle committen.

Und anstatt bun install auszuführen, führen Sie bun ci aus.

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

Plattformspezifische Abhängigkeiten?

Bun speichert normalisierte cpu- und os-Werte von npm in der Lockfile, zusammen mit den aufgelösten Paketen. Es überspringt das Herunterladen, Extrahieren und Installieren von Paketen, die für das aktuelle Ziel zur Laufzeit deaktiviert sind. Das bedeutet, dass sich die Lockfile zwischen Plattformen/Architekturen nicht ändert, auch wenn sich die letztendlich installierten Pakete ändern.

--cpu- und --os-Flags

Sie können die Zielplattform für die Paketauswahl überschreiben:

bun install --cpu=x64 --os=linux

Dies installiert Pakete für die angegebene Plattform statt für das aktuelle System. Nützlich für plattformübergreifende Builds oder beim Vorbereiten von Deployments für verschiedene Umgebungen.

Akzeptierte Werte für --cpu: arm64, x64, ia32, ppc64, s390x

Akzeptierte Werte für --os: linux, darwin, win32, freebsd, openbsd, sunos, aix

Peer-Abhängigkeiten?

Peer-Abhängigkeiten werden ähnlich wie bei yarn behandelt. bun install installiert automatisch Peer-Abhängigkeiten. Wenn die Abhängigkeit in peerDependenciesMeta als optional markiert ist, wird eine vorhandene Abhängigkeit gewählt, wenn möglich.

Lockfile

bun.lock ist Buns Lockfile-Format. Siehe unseren Blogbeitrag über die Text-Lockfile.

Vor Bun 1.2 war die Lockfile binär und hieß bun.lockb. Alte Lockfiles können in das neue Format aktualisiert werden, indem bun install --save-text-lockfile --frozen-lockfile --lockfile-only ausgeführt und dann bun.lockb gelöscht wird.

Cache

Um den Cache zu löschen:

bun pm cache rm
# oder
rm -rf ~/.bun/install/cache

Plattformspezifische Backends

bun install verwendet je nach Plattform unterschiedliche Systemaufrufe, um Abhängigkeiten zu installieren. Dies ist eine Leistungsoptimierung. Sie können ein bestimmtes Backend mit dem --backend-Flag erzwingen.

hardlink ist das Standard-Backend unter Linux. Benchmarking zeigte, dass es unter Linux das schnellste ist.

rm -rf node_modules
bun install --backend hardlink

clonefile ist das Standard-Backend unter macOS. Benchmarking zeigte, dass es unter macOS das schnellste ist. Es ist nur unter macOS verfügbar.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir ist ähnlich wie clonefile, außer dass es jede Datei einzeln pro Verzeichnis klont. Es ist nur unter macOS verfügbar und tendiert dazu, langsamer als clonefile zu sein. Im Gegensatz zu clonefile klont es Unterverzeichnisse nicht rekursiv in einem Systemaufruf.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile ist das Fallback, das verwendet wird, wenn eine der oben genannten Methoden fehlschlägt, und ist die langsamste. Unter macOS verwendet es fcopyfile() und unter Linux verwendet es copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink wird typischerweise nur intern für file:-Abhängigkeiten (und schließlich link:) verwendet. Um Endlosschleifen zu verhindern, überspringt es das Symlinking des node_modules-Ordners.

Wenn Sie mit --backend=symlink installieren, löst Node.js node_modules von Abhängigkeiten nicht auf, es sei denn, jede Abhängigkeit hat ihren eigenen node_modules-Ordner oder Sie übergeben --preserve-symlinks an node oder bun. Siehe Node.js-Dokumentation zu --preserve-symlinks.

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

npm-Registry-Metadaten

Bun verwendet ein binäres Format zum Cachen von NPM-Registry-Antworten. Dies lädt viel schneller als JSON und ist tendenziell kleiner auf der Festplatte. Sie werden diese Dateien in ~/.bun/install/cache/*.npm sehen. Das Dateinamenmuster ist ${hash(packageName)}.npm. Es ist ein Hash, damit keine zusätzlichen Verzeichnisse für gescopete Pakete erstellt werden müssen.

Buns Verwendung von Cache-Control ignoriert Age. Dies verbessert die Leistung, bedeutet aber, dass Bun etwa 5 Minuten veraltet sein kann, um die neuesten Paketversionsmetadaten von npm zu erhalten.

pnpm-Migration

Bun migriert automatisch Projekte von pnpm zu bun. Wenn eine pnpm-lock.yaml-Datei erkannt wird und keine bun.lock-Datei existiert, migriert Bun automatisch die Lockfile während der Installation zu bun.lock. Die ursprüngliche pnpm-lock.yaml-Datei bleibt unverändert.

bun install

Hinweis: Die Migration läuft nur, wenn bun.lock nicht vorhanden ist. Es gibt derzeit kein Opt-out-Flag für die pnpm-Migration.

Der Migrationsprozess behandelt:

Lockfile-Migration

• Konvertiert pnpm-lock.yaml in das bun.lock-Format
• Behält Paketversionen und Auflösungsinformationen bei
• Erhält Abhängigkeitsbeziehungen und Peer-Abhängigkeiten
• Behandelt gepatchte Abhängigkeiten mit Integritäts-Hashes

Workspace-Konfiguration

Wenn eine pnpm-workspace.yaml-Datei existiert, migriert Bun Workspace-Einstellungen in Ihre root package.json:

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

Die Workspace-Paketliste und Kataloge werden in das workspaces-Feld in package.json verschoben:

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

Katalog-Abhängigkeiten

Abhängigkeiten, die pnpms catalog:-Protokoll verwenden, werden beibehalten:

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

Konfigurationsmigration

Die folgende pnpm-Konfiguration wird sowohl von pnpm-lock.yaml als auch von pnpm-workspace.yaml migriert:

• Overrides: Von pnpm.overrides zu root-level overrides in package.json verschoben
• Gepatchte Abhängigkeiten: Von pnpm.patchedDependencies zu root-level patchedDependencies in package.json verschoben
• Workspace-Overrides: Von pnpm-workspace.yaml auf root package.json angewendet

Anforderungen

• Erfordert pnpm-Lockfile-Version 7 oder höher
• Workspace-Pakete müssen ein name-Feld in ihrer package.json haben
• Alle Katalogeinträge, auf die von Abhängigkeiten verwiesen wird, müssen in der Katalogdefinition existieren

Nach der Migration können Sie pnpm-lock.yaml und pnpm-workspace.yaml-Dateien sicher entfernen.