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

Uso básico

bun install react
bun install react@19.1.1 # versión específica
bun install react@latest # etiqueta específica

El CLI bun contiene un gestor de paquetes compatible con Node.js diseñado para ser un reemplazo dramáticamente más rápido para npm, yarn, y pnpm. Es una herramienta independiente que funcionará en proyectos Node.js preexistentes; si tu proyecto tiene un package.json, bun install puede ayudarte a acelerar tu flujo de trabajo.

NOTE

⚡️ 25 veces más rápido — Cambia de npm install a bun install en cualquier proyecto Node.js para hacer tus instalaciones hasta 25 veces más rápidas.

Para usuarios de Linux

La versión mínima recomendada del kernel de Linux es 5.6. Si estás en kernel de Linux 5.1 - 5.5, bun install funcionará, pero las solicitudes HTTP serán lentas debido a la falta de soporte para la operación connect() de io_uring.

Si estás usando Ubuntu 20.04, así es cómo instalar un kernel más nuevo:

# Si esto devuelve una versión >= 5.6, no necesitas hacer nada
uname -r

# Instalar el kernel de habilitación de hardware oficial de Ubuntu
sudo apt install --install-recommends linux-generic-hwe-20.04

Para instalar todas las dependencias de un proyecto:

bun install

Ejecutar bun install:

• Instalará todas las dependencies, devDependencies, y optionalDependencies. Bun instalará peerDependencies por defecto.
• Ejecutará tus scripts {pre|post}install y {pre|post}prepare del proyecto en el momento apropiado. Por razones de seguridad Bun no ejecuta scripts de ciclo de vida de dependencias instaladas.
• Escribirá un lockfile bun.lock en la raíz del proyecto.

---

Registro

Para modificar la verbosidad del registro:

bun install --verbose # registro de depuración
bun install --silent  # sin registro

---

Scripts de ciclo de vida

A diferencia de otros clientes npm, Bun no ejecuta scripts de ciclo de vida arbitrarios como postinstall para dependencias instaladas. Ejecutar scripts arbitrarios representa un riesgo de seguridad potencial.

Para decirle a Bun que permita scripts de ciclo de vida para un paquete en particular, agrega el paquete a trustedDependencies en tu package.json.

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

Luego vuelve a instalar el paquete. Bun leerá este campo y ejecutará scripts de ciclo de vida para my-trusted-package.

Los scripts de ciclo de vida se ejecutarán en paralelo durante la instalación. Para ajustar el número máximo de scripts concurrentes, usa la bandera --concurrent-scripts. El predeterminado es dos veces el conteo de cpu reportado o GOMAXPROCS.

bun install --concurrent-scripts 5

Bun optimiza automáticamente los scripts postinstall para paquetes populares (como esbuild, sharp, etc.) determinando qué scripts necesitan ejecutarse. Para deshabilitar estas optimizaciones:

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

Espacios de trabajo

Bun soporta "workspaces" en package.json. Para documentación completa referirse a Package manager > Workspaces.

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

---

Instalar dependencias para paquetes específicos

En un monorepo, puedes instalar las dependencias para un subconjunto de paquetes usando la bandera --filter.

# Instalar dependencias para todos los espacios de trabajo excepto `pkg-c`
bun install --filter '!pkg-c'

# Instalar dependencias solo para `pkg-a` en `./packages/pkg-a`
bun install --filter './packages/pkg-a'

Para más información sobre filtrado con bun install, referirse a Package Manager > Filtering

---

Anulaciones y resoluciones

Bun soporta "overrides" de npm y "resolutions" de Yarn en package.json. Estos son mecanismos para especificar un rango de versiones para metadependencias—las dependencias de tus dependencias. Referirse a Package manager > Overrides and resolutions para documentación completa.

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

---

Paquetes globales

Para instalar un paquete globalmente, usa la bandera -g/--global. Típicamente esto se usa para instalar herramientas de línea de comandos.

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

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

---

Modo de producción

Para instalar en modo de producción (es decir, sin devDependencies o optionalDependencies):

bun install --production

Para instalaciones reproducibles, usa --frozen-lockfile. Esto instalará las versiones exactas de cada paquete especificadas en el lockfile. Si tu package.json no coincide con bun.lock, Bun saldrá con un error. El lockfile no se actualizará.

bun install --frozen-lockfile

Para más información sobre el lockfile de Bun bun.lock, referirse a Package manager > Lockfile.

---

Omitir dependencias

Para omitir dependencias dev, peer, u opcionales usa la bandera --omit.

# Excluir "devDependencies" de la instalación. Esto se aplicará al
# package raíz y espacios de trabajo si existen. Las dependencias transitivas no
# tendrán "devDependencies".
bun install --omit dev

# Instalar solo dependencias de "dependencies"
bun install --omit=dev --omit=peer --omit=optional

---

Ejecución en seco

Para realizar una ejecución en seco (es decir, no instalar realmente nada):

bun install --dry-run

---

Dependencias no-npm

Bun soporta instalar dependencias desde Git, GitHub, y tarballs alojados localmente o remotamente. Para documentación completa referirse a Package manager > Git, GitHub, and tarball dependencies.

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

---

Estrategias de instalación

Bun soporta dos estrategias de instalación de paquetes que determinan cómo se organizan las dependencias en node_modules:

Instalaciones hoisted

El enfoque tradicional de npm/Yarn que aplana las dependencias en un directorio node_modules compartido:

bun install --linker hoisted

Instalaciones aisladas

Un enfoque similar a pnpm que crea un aislamiento estricto de dependencias para prevenir dependencias fantasma:

bun install --linker isolated

Las instalaciones aisladas crean un almacén central de paquetes en node_modules/.bun/ con symlinks en el node_modules de nivel superior. Esto asegura que los paquetes solo puedan acceder a sus dependencias declaradas.

Estrategia predeterminada

La estrategia de linker predeterminada depende de si estás comenzando desde cero o tienes un proyecto existente:

• Nuevos espacios de trabajo/monorepos: isolated (previene dependencias fantasma)
• Nuevos proyectos de un solo paquete: hoisted (comportamiento tradicional de npm)
• Proyectos existentes (creados pre-v1.3.2): hoisted (preserva la compatibilidad hacia atrás)

El predeterminado está controlado por un campo configVersion en tu lockfile. Para una explicación detallada, ver Package manager > Isolated installs.

---

Edad mínima de lanzamiento

Para proteger contra ataques a la cadena de suministro donde paquetes maliciosos se publican rápidamente, puedes configurar un requisito de edad mínima para paquetes npm. Las versiones de paquetes publicadas más recientemente que el umbral especificado (en segundos) se filtrarán durante la instalación.

# Instalar solo versiones de paquetes publicadas hace al menos 3 días
bun add @types/bun --minimum-release-age 259200 # segundos

También puedes configurar esto en bunfig.toml:

[install]
# Instalar solo versiones de paquetes publicadas hace al menos 3 días
minimumReleaseAge = 259200 # segundos

# Excluir paquetes de confianza de la restricción de edad
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Cuando el filtro de edad mínima está activo:

• Solo afecta la resolución de nuevos paquetes - los paquetes existentes en bun.lock permanecen sin cambios
• Todas las dependencias (directas y transitivas) se filtran para cumplir con el requisito de edad al ser resueltas
• Cuando las versiones son bloqueadas por la restricción de edad, una verificación de estabilidad detecta patrones de corrección de errores rápidos
  • Si múltiples versiones fueron publicadas cerca juntas justo fuera de tu restricción de edad, extiende el filtro para omitir esas versiones potencialmente inestables y selecciona una versión anterior más madura
  • Busca hasta 7 días después de la restricción de edad, sin embargo si aún encuentra lanzamientos rápidos ignora la verificación de estabilidad
  • Las solicitudes de versión exacta (como package@1.1.1) aún respetan la restricción de edad pero omiten la verificación de estabilidad
• Las versiones sin un campo time se tratan como que pasan la verificación de edad (el registro npm siempre debería proporcionar marcas de tiempo)

Para escaneo de seguridad más avanzado, incluyendo integración con servicios y filtrado personalizado, ver Package manager > Security Scanner API.

---

Configuración

Configurar bun install con bunfig.toml

bunfig.toml se busca en las siguientes rutas en bun install, bun remove, y bun add:

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

Si ambos se encuentran, los resultados se fusionan.

Configurar con bunfig.toml es opcional. Bun intenta ser sin configuración en general, pero eso no siempre es posible. El comportamiento predeterminado de bun install puede configurarse en bunfig.toml. Los valores predeterminados se muestran abajo.

[install]

# si instalar optionalDependencies
optional = true

# si instalar devDependencies
dev = true

# si instalar peerDependencies
peer = true

# equivalente a la bandera `--production`
production = false

# equivalente a la bandera `--save-text-lockfile`
saveTextLockfile = false

# equivalente a la bandera `--frozen-lockfile`
frozenLockfile = false

# equivalente a la bandera `--dry-run`
dryRun = false

# equivalente a la bandera `--concurrent-scripts`
concurrentScripts = 16 # (conteo de cpu o GOMAXPROCS) x2

# estrategia de instalación: "hoisted" o "isolated"
# el predeterminado depende del configVersion del lockfile y workspaces:
# - configVersion = 1: "isolated" si usa workspaces, de lo contrario "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# configuración de edad mínima
minimumReleaseAge = 259200 # segundos
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Configurar con variables de entorno

Las variables de entorno tienen una prioridad más alta que bunfig.toml.

Nombre	Descripción
BUN_CONFIG_REGISTRY	Establecer un registro npm (predeterminado: https://registry.npmjs.org)
BUN_CONFIG_TOKEN	Establecer un token de autenticación (actualmente no hace nada)
BUN_CONFIG_YARN_LOCKFILE	Guardar un yarn.lock estilo Yarn v1
BUN_CONFIG_LINK_NATIVE_BINS	Apuntar bin en package.json a una dependencia específica de plataforma
BUN_CONFIG_SKIP_SAVE_LOCKFILE	No guardar un lockfile
BUN_CONFIG_SKIP_LOAD_LOCKFILE	No cargar un lockfile
BUN_CONFIG_SKIP_INSTALL_PACKAGES	No instalar ningún paquete

Bun siempre intenta usar el método de instalación más rápido disponible para la plataforma objetivo. En macOS, eso es clonefile y en Linux, eso es hardlink. Puedes cambiar qué método de instalación se usa con la bandera --backend. Cuando no está disponible o hay error, clonefile y hardlink recurren a una implementación específica de plataforma de copiar archivos.

Bun almacena paquetes instalados desde npm en ~/.bun/install/cache/${name}@${version}. Nota que si la versión semver tiene una etiqueta build o pre, se reemplaza con un hash de ese valor. Esto es para reducir las posibilidades de errores por rutas de archivo largas, pero desafortunadamente complica descubrir dónde se instaló un paquete en el disco.

Cuando la carpeta node_modules existe, antes de instalar, Bun verifica si el "name" y "version" en package/package.json en la carpeta node_modules esperada coincide con el name y version esperados. Así es como determina si debería instalar. Usa un analizador JSON personalizado que deja de analizar tan pronto como encuentra "name" y "version".

Cuando un bun.lock no existe o package.json ha cambiado dependencias, los tarballs se descargan y extraen ansiosamente mientras se resuelven.

Cuando un bun.lock existe y package.json no ha cambiado, Bun descarga dependencias faltantes perezosamente. Si el paquete con un name y version coincidentes ya existe en la ubicación esperada dentro de node_modules, Bun no intentará descargar el tarball.

CI/CD

Usa la acción oficial oven-sh/setup-bun para instalar bun en un pipeline de 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

Para entornos CI/CD que quieren asegurar compilaciones reproducibles, usa bun ci para fallar la compilación si el package.json está fuera de sincronía con el lockfile:

bun ci

Esto es equivalente a bun install --frozen-lockfile. Instala versiones exactas desde bun.lock y falla si package.json no coincide con el lockfile. Para usar bun ci o bun install --frozen-lockfile, debes confirmar bun.lock al control de versiones.

Y en lugar de ejecutar bun install, ejecuta 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

¿Dependencias específicas de plataforma?

bun almacena valores normalizados de cpu y os desde npm en el lockfile, junto con los paquetes resueltos. Omite descargar, extraer, e instalar paquetes deshabilitados para el objetivo actual en runtime. Esto significa que el lockfile no cambiará entre plataformas/arquitecturas incluso si los paquetes finalmente instalados cambian.

Banderas --cpu y --os

Puedes sobrescribir la plataforma objetivo para la selección de paquetes:

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

Esto instala paquetes para la plataforma especificada en lugar del sistema actual. Útil para compilaciones multi-plataforma o al preparar despliegues para diferentes entornos.

Valores aceptados para --cpu: arm64, x64, ia32, ppc64, s390x

Valores aceptados para --os: linux, darwin, win32, freebsd, openbsd, sunos, aix

¿Dependencias peer?

Las dependencias peer se manejan de manera similar a yarn. bun install instalará automáticamente dependencias peer. Si la dependencia está marcada como opcional en peerDependenciesMeta, se elegirá una dependencia existente si es posible.

Lockfile

bun.lock es el formato de lockfile de Bun. Ver nuestra publicación de blog sobre el lockfile de texto.

Antes de Bun 1.2, el lockfile era binario y se llamaba bun.lockb. Los lockfiles antiguos pueden actualizarse al nuevo formato ejecutando bun install --save-text-lockfile --frozen-lockfile --lockfile-only, y luego eliminando bun.lockb.

Caché

Para eliminar la caché:

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

Backends específicos de plataforma

bun install usa diferentes llamadas al sistema para instalar dependencias dependiendo de la plataforma. Esto es una optimización de rendimiento. Puedes forzar un backend específico con la bandera --backend.

hardlink es el backend predeterminado en Linux. Las pruebas de rendimiento mostraron que es el más rápido en Linux.

rm -rf node_modules
bun install --backend hardlink

clonefile es el backend predeterminado en macOS. Las pruebas de rendimiento mostraron que es el más rápido en macOS. Solo está disponible en macOS.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir es similar a clonefile, excepto que clona cada archivo individualmente por directorio. Solo está disponible en macOS y tiende a tener un rendimiento más lento que clonefile. A diferencia de clonefile, esto no clona recursivamente subdirectorios en una llamada al sistema.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile es el fallback usado cuando cualquiera de los anteriores falla, y es el más lento. en macOS, usa fcopyfile() y en linux usa copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink típicamente solo se usa para dependencias file: (y eventualmente link:) internamente. Para prevenir bucles infinitos, omite crear symlinks en la carpeta node_modules.

Si instalas con --backend=symlink, Node.js no resolverá los node_modules de las dependencias a menos que cada dependencia tenga su propia carpeta node_modules o pases --preserve-symlinks a node o bun. Ver documentación de Node.js sobre --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

Metadatos del registro npm

Bun usa un formato binario para cachear respuestas del registro NPM. Esto carga mucho más rápido que JSON y tiende a ser más pequeño en disco. Verás estos archivos en ~/.bun/install/cache/*.npm. El patrón de nombre de archivo es ${hash(packageName)}.npm. Es un hash para que no necesiten crearse directorios adicionales para paquetes con scope.

El uso de Cache-Control de Bun ignora Age. Esto mejora el rendimiento, pero significa que bun puede estar aproximadamente 5 minutos desactualizado para recibir los últimos metadatos de versión de paquetes desde npm.

Migración desde pnpm

Bun migra automáticamente proyectos desde pnpm a bun. Cuando se detecta un archivo pnpm-lock.yaml y no existe un archivo bun.lock, Bun migrará automáticamente el lockfile a bun.lock durante la instalación. El archivo pnpm-lock.yaml original permanece sin modificar.

bun install

Nota: La migración solo se ejecuta cuando bun.lock está ausente. Actualmente no hay una bandera para optar por no usar la migración desde pnpm.

El proceso de migración maneja:

Migración de lockfile

• Convierte pnpm-lock.yaml al formato bun.lock
• Preserva versiones de paquetes e información de resolución
• Mantiene relaciones de dependencias y dependencias peer
• Maneja dependencias parcheadas con hashes de integridad

Configuración de espacio de trabajo

Cuando existe un archivo pnpm-workspace.yaml, Bun migra configuraciones de espacio de trabajo a tu package.json raíz:

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

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

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

La lista de paquetes del espacio de trabajo y los catálogos se mueven al campo workspaces en 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"
      }
    }
  }
}

Dependencias de catálogo

Las dependencias que usan el protocolo catalog: de pnpm se preservan:

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

Migración de configuración

La siguiente configuración de pnpm se migra desde pnpm-lock.yaml y pnpm-workspace.yaml:

• Anulaciones: Movidas desde pnpm.overrides a overrides de nivel raíz en package.json
• Dependencias parcheadas: Movidas desde pnpm.patchedDependencies a patchedDependencies de nivel raíz en package.json
• Anulaciones de espacio de trabajo: Aplicadas desde pnpm-workspace.yaml a package.json raíz

Requisitos

• Requiere versión de lockfile de pnpm 7 o superior
• Los paquetes del espacio de trabajo deben tener un campo name en su package.json
• Todas las entradas de catálogo referenciadas por dependencias deben existir en la definición de catálogos

Después de la migración, puedes eliminar de forma segura los archivos pnpm-lock.yaml y pnpm-workspace.yaml.