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

Utilisation de base

bun install react
bun install react@19.1.1 # version spécifique
bun install react@latest # tag spécifique

Le CLI bun contient un gestionnaire de packages compatible avec Node.js conçu pour être un remplacement considérablement plus rapide de npm, yarn et pnpm. C'est un outil autonome qui fonctionnera dans des projets Node.js préexistants ; si votre projet a un package.json, bun install peut vous aider à accélérer votre flux de travail.

NOTE

⚡️ 25 fois plus rapide — Passez de npm install à bun install dans n'importe quel projet Node.js pour rendre vos installations jusqu'à 25 fois plus rapides.

Pour les utilisateurs Linux

La version minimale recommandée du noyau Linux est 5.6. Si vous êtes sur un noyau Linux 5.1 - 5.5, bun install fonctionnera, mais les requêtes HTTP seront lentes en raison d'un manque de prise en charge de l'opération connect() de io_uring.

Si vous utilisez Ubuntu 20.04, voici comment installer un noyau plus récent :

# Si cela retourne une version >= 5.6, vous n'avez rien à faire
uname -r

# Installer le noyau hardware enablement officiel Ubuntu
sudo apt install --install-recommends linux-generic-hwe-20.04

Pour installer toutes les dépendances d'un projet :

bun install

L'exécution de bun install va :

• Installer toutes les dependencies, devDependencies et optionalDependencies. Bun installera les peerDependencies par défaut.
• Exécuter vos scripts {pre|post}install et {pre|post}prepare de projet au moment approprié. Pour des raisons de sécurité, Bun n'exécute pas les scripts de cycle de vie des dépendances installées.
• Écrire un lockfile bun.lock à la racine du projet.

---

Journalisation

Pour modifier la verbosité de la journalisation :

bun install --verbose # journalisation debug
bun install --silent  # pas de journalisation

---

Scripts de cycle de vie

Contrairement à d'autres clients npm, Bun n'exécute pas de scripts de cycle de vie arbitraires comme postinstall pour les dépendances installées. L'exécution de scripts arbitraires représente un risque de sécurité potentiel.

Pour dire à Bun d'autoriser les scripts de cycle de vie pour un package particulier, ajoutez le package à trustedDependencies dans votre package.json.

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

Puis réinstallez le package. Bun lira ce champ et exécutera les scripts de cycle de vie pour my-trusted-package.

Les scripts de cycle de vie s'exécuteront en parallèle pendant l'installation. Pour ajuster le nombre maximum de scripts concurrents, utilisez le drapeau --concurrent-scripts. La valeur par défaut est deux fois le nombre de cpu signalé ou GOMAXPROCS.

bun install --concurrent-scripts 5

Bun optimise automatiquement les scripts postinstall pour les packages populaires (comme esbuild, sharp, etc.) en déterminant quels scripts doivent s'exécuter. Pour désactiver ces optimisations :

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

Workspaces

Bun prend en charge "workspaces" dans package.json. Pour la documentation complète, consultez Package manager > Workspaces.

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

---

Installation des dépendances pour des packages spécifiques

Dans un monorepo, vous pouvez installer les dépendances pour un sous-ensemble de packages en utilisant le drapeau --filter.

# Installer les dépendances pour tous les workspaces sauf `pkg-c`
bun install --filter '!pkg-c'

# Installer les dépendances uniquement pour `pkg-a` dans `./packages/pkg-a`
bun install --filter './packages/pkg-a'

Pour plus d'informations sur le filtrage avec bun install, consultez Package Manager > Filtrage

---

Overrides et résolutions

Bun prend en charge les "overrides" de npm et les "resolutions" de Yarn dans package.json. Ce sont des mécanismes pour spécifier une plage de versions pour les métadépendances—les dépendances de vos dépendances. Consultez Package manager > Overrides et résolutions pour la documentation complète.

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

---

Packages globaux

Pour installer un package globalement, utilisez le drapeau -g/--global. Généralement, cela est utilisé pour installer des outils en ligne de commande.

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

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

---

Mode production

Pour installer en mode production (c'est-à-dire sans devDependencies ou optionalDependencies) :

bun install --production

Pour des installations reproductibles, utilisez --frozen-lockfile. Cela installera les versions exactes de chaque package spécifiées dans le lockfile. Si votre package.json ne correspond pas à bun.lock, Bun se terminera avec une erreur. Le lockfile ne sera pas mis à jour.

bun install --frozen-lockfile

Pour plus d'informations sur le lockfile bun.lock de Bun, consultez Package manager > Lockfile.

---

Omission de dépendances

Pour omettre les dépendances dev, peer ou optionnelles, utilisez le drapeau --omit.

# Exclure "devDependencies" de l'installation. Cela s'appliquera au
# package racine et aux workspaces s'ils existent. Les dépendances transitives n'auront
# pas de "devDependencies".
bun install --omit dev

# Installer uniquement les dépendances de "dependencies"
bun install --omit=dev --omit=peer --omit=optional

---

Simulation

Pour effectuer une simulation (c'est-à-dire ne rien installer réellement) :

bun install --dry-run

---

Dépendances non-npm

Bun prend en charge l'installation de dépendances depuis Git, GitHub et des tarballs hébergés localement ou à distance. Pour la documentation complète, consultez Package manager > Dépendances Git, GitHub et tarball.

{
  "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"
  }
}

---

Stratégies d'installation

Bun prend en charge deux stratégies d'installation de packages qui déterminent comment les dépendances sont organisées dans node_modules :

Installations hoisted

L'approche traditionnelle npm/Yarn qui aplatit les dépendances dans un répertoire node_modules partagé :

bun install --linker hoisted

Installations isolées

Une approche similaire à pnpm qui crée une isolation stricte des dépendances pour empêcher les dépendances fantômes :

bun install --linker isolated

Les installations isolées créent un store de packages central dans node_modules/.bun/ avec des liens symboliques dans le node_modules de niveau supérieur. Cela garantit que les packages ne peuvent accéder qu'à leurs dépendances déclarées.

Stratégie par défaut

La stratégie de linker par défaut dépend du fait que vous commenciez un nouveau projet ou ayez un projet existant :

• Nouveaux workspaces/monorepos : isolated (empêche les dépendances fantômes)
• Nouveaux projets à package unique : hoisted (comportement npm traditionnel)
• Projets existants (créés avant v1.3.2) : hoisted (préserve la compatibilité ascendante)

La valeur par défaut est contrôlée par un champ configVersion dans votre lockfile. Pour une explication détaillée, consultez Package manager > Installations isolées.

---

Âge minimum de publication

Pour se protéger contre les attaques de la chaîne d'approvisionnement où des packages malveillants sont rapidement publiés, vous pouvez configurer une exigence d'âge minimum pour les packages npm. Les versions de packages publiées plus récemment que le seuil spécifié (en secondes) seront filtrées pendant l'installation.

# Installer uniquement les versions de packages publiées il y a au moins 3 jours
bun add @types/bun --minimum-release-age 259200 # secondes

Vous pouvez également configurer cela dans bunfig.toml :

[install]
# Installer uniquement les versions de packages publiées il y a au moins 3 jours
minimumReleaseAge = 259200 # secondes

# Exclure les packages de confiance de la limite d'âge
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Lorsque le filtre d'âge minimum est actif :

• Affecte uniquement la nouvelle résolution de packages - les packages existants dans bun.lock restent inchangés
• Toutes les dépendances (directes et transitives) sont filtrées pour respecter l'exigence d'âge lors de la résolution
• Lorsque les versions sont bloquées par la limite d'âge, une vérification de stabilité détecte les modèles de correction de bugs rapides
  • Si plusieurs versions ont été publiées à proximité juste en dehors de votre limite d'âge, elle étend le filtre pour ignorer ces versions potentiellement instables et sélectionne une version plus ancienne et plus mature
  • Recherche jusqu'à 7 jours après la limite d'âge, cependant si elle trouve toujours des publications rapides, elle ignore la vérification de stabilité
  • Les demandes de version exactes (comme package@1.1.1) respectent toujours la limite d'âge mais contournent la vérification de stabilité
• Les versions sans champ time sont traitées comme passant la vérification d'âge (le registre npm devrait toujours fournir des horodatages)

Pour une analyse de sécurité plus avancée, y compris l'intégration avec des services et un filtrage personnalisé, consultez Package manager > API de scanner de sécurité.

---

Configuration

Configuration de bun install avec bunfig.toml

bunfig.toml est recherché dans les chemins suivants lors de bun install, bun remove et bun add :

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

Si les deux sont trouvés, les résultats sont fusionnés.

La configuration avec bunfig.toml est optionnelle. Bun essaie d'être zéro configuration en général, mais ce n'est pas toujours possible. Le comportement par défaut de bun install peut être configuré dans bunfig.toml. Les valeurs par défaut sont indiquées ci-dessous.

[install]

# s'il faut installer optionalDependencies
optional = true

# s'il faut installer devDependencies
dev = true

# s'il faut installer peerDependencies
peer = true

# équivalent au drapeau `--production`
production = false

# équivalent au drapeau `--save-text-lockfile`
saveTextLockfile = false

# équivalent au drapeau `--frozen-lockfile`
frozenLockfile = false

# équivalent au drapeau `--dry-run`
dryRun = false

# équivalent au drapeau `--concurrent-scripts`
concurrentScripts = 16 # (nombre de cpu ou GOMAXPROCS) x2

# stratégie d'installation : "hoisted" ou "isolated"
# la valeur par défaut dépend du configVersion du lockfile et des workspaces :
# - configVersion = 1 : "isolated" si utilisation de workspaces, sinon "hoisted"
# - configVersion = 0 : "hoisted"
linker = "hoisted"


# configuration de l'âge minimum
minimumReleaseAge = 259200 # secondes
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Configuration avec des variables d'environnement

Les variables d'environnement ont une priorité plus élevée que bunfig.toml.

Nom	Description
BUN_CONFIG_REGISTRY	Définir un registre npm (par défaut : https://registry.npmjs.org)
BUN_CONFIG_TOKEN	Définir un token d'authentification (ne fait actuellement rien)
BUN_CONFIG_YARN_LOCKFILE	Sauvegarder un yarn.lock de style Yarn v1
BUN_CONFIG_LINK_NATIVE_BINS	Pointer bin dans package.json vers une dépendance spécifique à la plateforme
BUN_CONFIG_SKIP_SAVE_LOCKFILE	Ne pas sauvegarder de lockfile
BUN_CONFIG_SKIP_LOAD_LOCKFILE	Ne pas charger de lockfile
BUN_CONFIG_SKIP_INSTALL_PACKAGES	Ne pas installer de packages

Bun essaie toujours d'utiliser la méthode d'installation la plus rapide disponible pour la plateforme cible. Sur macOS, c'est clonefile et sur Linux, c'est hardlink. Vous pouvez changer la méthode d'installation utilisée avec le drapeau --backend. Lorsqu'elle n'est pas disponible ou en cas d'erreur, clonefile et hardlink se rabattent sur une implémentation spécifique à la plateforme de copie de fichiers.

Bun stocke les packages installés depuis npm dans ~/.bun/install/cache/${name}@${version}. Notez que si la version semver a un tag build ou pre, il est remplacé par un hachage de cette valeur. Cela réduit les risques d'erreurs dues aux longs chemins de fichiers, mais complique malheureusement la détermination de l'emplacement d'installation d'un package sur le disque.

Lorsque le dossier node_modules existe, avant d'installer, Bun vérifie si le "name" et "version" dans package/package.json dans le dossier node_modules attendu correspondent au name et version attendus. C'est ainsi qu'il détermine s'il doit installer. Il utilise un analyseur JSON personnalisé qui s'arrête dès qu'il trouve "name" et "version".

Lorsqu'un bun.lock n'existe pas ou que package.json a changé de dépendances, les tarballs sont téléchargés et extraits avec empressement pendant la résolution.

Lorsqu'un bun.lock existe et que package.json n'a pas changé de dépendances, Bun télécharge les dépendances manquantes paresseusement. Si le package avec un name et version correspondants existe déjà à l'emplacement attendu dans node_modules, Bun n'essaiera pas de télécharger le tarball.

CI/CD

Utilisez l'action officielle oven-sh/setup-bun pour installer bun dans un pipeline GitHub Actions :

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

Pour les environnements CI/CD qui souhaitent appliquer des builds reproductibles, utilisez bun ci pour échouer le build si le package.json n'est pas synchronisé avec le lockfile :

bun ci

Ceci est équivalent à bun install --frozen-lockfile. Cela installe les versions exactes depuis bun.lock et échoue si package.json ne correspond pas au lockfile. Pour utiliser bun ci ou bun install --frozen-lockfile, vous devez committer bun.lock dans le contrôle de version.

Et au lieu d'exécuter bun install, exécutez bun ci.

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

Dépendances spécifiques à la plateforme ?

bun stocke les valeurs normalisées cpu et os de npm dans le lockfile, ainsi que les packages résolus. Il ignore le téléchargement, l'extraction et l'installation des packages désactivés pour la cible actuelle au moment de l'exécution. Cela signifie que le lockfile ne changera pas entre les plates-formes/architectures même si les packages finalement installés changent.

Drapeaux --cpu et --os

Vous pouvez remplacer la plateforme cible pour la sélection de packages :

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

Ceci installe des packages pour la plateforme spécifiée au lieu du système actuel. Utile pour les builds multi-plateformes ou lors de la préparation de déploiements pour différents environnements.

Valeurs acceptées pour --cpu : arm64, x64, ia32, ppc64, s390x

Valeurs acceptées pour --os : linux, darwin, win32, freebsd, openbsd, sunos, aix

Dépendances peer ?

Les dépendances peer sont gérées de manière similaire à yarn. bun install installera automatiquement les dépendances peer. Si la dépendance est marquée comme optionnelle dans peerDependenciesMeta, une dépendance existante sera choisie si possible.

Lockfile

bun.lock est le format de lockfile de Bun. Consultez notre article de blog sur le lockfile texte.

Avant Bun 1.2, le lockfile était binaire et s'appelait bun.lockb. Les anciens lockfiles peuvent être mis à niveau vers le nouveau format en exécutant bun install --save-text-lockfile --frozen-lockfile --lockfile-only, puis en supprimant bun.lockb.

Cache

Pour supprimer le cache :

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

Backends spécifiques à la plateforme

bun install utilise différents appels système pour installer les dépendances selon la plateforme. C'est une optimisation de performance. Vous pouvez forcer un backend spécifique avec le drapeau --backend.

hardlink est le backend par défaut sur Linux. Les benchmarks ont montré qu'il était le plus rapide sur Linux.

rm -rf node_modules
bun install --backend hardlink

clonefile est le backend par défaut sur macOS. Les benchmarks ont montré qu'il était le plus rapide sur macOS. Il est uniquement disponible sur macOS.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir est similaire à clonefile, sauf qu'il clone chaque fichier individuellement par répertoire. Il est uniquement disponible sur macOS et a tendance à être plus lent que clonefile. Contrairement à clonefile, cela ne clone pas récursivement les sous-répertoires en un seul appel système.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile est le repli utilisé lorsque l'un des ci-dessus échoue, et est le plus lent. sur macOS, il utilise fcopyfile() et sur linux il utilise copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink est généralement utilisé uniquement pour les dépendances file: (et éventuellement link:) en interne. Pour éviter les boucles infinies, il ignore la création de liens symboliques pour le dossier node_modules.

Si vous installez avec --backend=symlink, Node.js ne résoudra pas les node_modules des dépendances à moins que chaque dépendance ait son propre dossier node_modules ou que vous passiez --preserve-symlinks à node ou bun. Consultez la documentation Node.js sur --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

Métadonnées du registre npm

Bun utilise un format binaire pour mettre en cache les réponses du registre NPM. Cela se charge beaucoup plus rapidement que JSON et a tendance à être plus petit sur le disque. Vous verrez ces fichiers dans ~/.bun/install/cache/*.npm. Le motif de nom de fichier est ${hash(packageName)}.npm. C'est un hachage pour que des répertoires supplémentaires n'aient pas besoin d'être créés pour les packages scoped.

L'utilisation de Cache-Control par Bun ignore Age. Cela améliore les performances, mais signifie que bun peut être en retard d'environ 5 minutes pour recevoir les dernières métadonnées de version de package depuis npm.

Migration pnpm

Bun migre automatiquement les projets depuis pnpm vers bun. Lorsqu'un fichier pnpm-lock.yaml est détecté et qu'aucun fichier bun.lock n'existe, Bun migrera automatiquement le lockfile vers bun.lock pendant l'installation. Le fichier pnpm-lock.yaml original reste non modifié.

bun install

Note : La migration s'exécute uniquement lorsque bun.lock est absent. Il n'y a actuellement aucun drapeau pour désactiver la migration pnpm.

Le processus de migration gère :

Migration du lockfile

• Convertit pnpm-lock.yaml au format bun.lock
• Préserve les versions de packages et les informations de résolution
• Maintient les relations de dépendances et les dépendances peer
• Gère les dépendances patchées avec des hachages d'intégrité

Configuration des workspaces

Lorsqu'un fichier pnpm-workspace.yaml existe, Bun migre les paramètres des workspaces vers votre package.json racine :

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

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

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

La liste des packages des workspaces et les catalogues sont déplacés vers le champ workspaces dans package.json :

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

Dépendances de catalogue

Les dépendances utilisant le protocole catalog: de pnpm sont préservées :

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

Migration de configuration

La configuration pnpm suivante est migrée depuis pnpm-lock.yaml et pnpm-workspace.yaml :

• Overrides : Déplacés de pnpm.overrides vers overrides de niveau racine dans package.json
• Dépendances patchées : Déplacées de pnpm.patchedDependencies vers patchedDependencies de niveau racine dans package.json
• Overrides de workspace : Appliqués depuis pnpm-workspace.yaml vers package.json racine

Exigences

• Nécessite la version 7 ou supérieure du lockfile pnpm
• Les packages de workspace doivent avoir un champ name dans leur package.json
• Toutes les entrées de catalogue référencées par les dépendances doivent exister dans la définition des catalogues

Après la migration, vous pouvez supprimer en toute sécurité les fichiers pnpm-lock.yaml et pnpm-workspace.yaml.

---