bun install

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

Uso básico

bash

bun install react
bun install react@19.1.1 # versão específica
bun install react@latest # tag específica

O CLI bun contém um gerenciador de pacotes compatível com Node.js projetado para ser um substituto dramaticamente mais rápido para npm, yarn e pnpm. É uma ferramenta autônoma que funcionará em projetos Node.js pré-existentes; se seu projeto tem um package.json, bun install pode ajudá-lo a acelerar seu fluxo de trabalho.

NOTE

⚡️ 25x mais rápido — Mude de npm install para bun install em qualquer projeto Node.js para tornar suas instalações até 25x mais rápidas.

Comparação de velocidade de instalação do Bun

Para usuários Linux

A versão mínima recomendada do Kernel Linux é 5.6. Se você estiver no kernel Linux 5.1 - 5.5, bun install funcionará, mas as requisições HTTP serão lentas devido à falta de suporte para a operação connect() do io_uring.

Se você estiver usando Ubuntu 20.04, veja como instalar um kernel mais novo:

bash

# Se isso retornar uma versão >= 5.6, você não precisa fazer nada
uname -r

# Instalar o kernel de habilitação de hardware oficial do Ubuntu
sudo apt install --install-recommends linux-generic-hwe-20.04

Para instalar todas as dependências de um projeto:

bash

bun install

Executar bun install irá:

Instalar todas as dependencies, devDependencies e optionalDependencies. O Bun instalará peerDependencies por padrão.
Executar scripts {pre|post}install e {pre|post}prepare do seu projeto no momento apropriado. Por razões de segurança, o Bun não executa scripts de ciclo de vida de dependências instaladas.
Escrever um lockfile bun.lock na raiz do projeto.

Logging

Para modificar a verbosidade do logging:

bash

bun install --verbose # logging de debug
bun install --silent  # sem logging

Scripts de ciclo de vida

Ao contrário de outros clientes npm, o Bun não executa scripts de ciclo de vida arbitrários como postinstall para dependências instaladas. Executar scripts arbitrários representa um risco de segurança potencial.

Para dizer ao Bun para permitir scripts de ciclo de vida para um pacote específico, adicione o pacote a trustedDependencies no seu package.json.

json

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

Em seguida, reinstale o pacote. O Bun lerá este campo e executará scripts de ciclo de vida para my-trusted-package.

Scripts de ciclo de vida serão executados em paralelo durante a instalação. Para ajustar o número máximo de scripts concorrentes, use a flag --concurrent-scripts. O padrão é duas vezes a contagem de CPUs relatada ou GOMAXPROCS.

bash

bun install --concurrent-scripts 5

O Bun otimiza automaticamente scripts postinstall para pacotes populares (como esbuild, sharp, etc.) determinando quais scripts precisam ser executados. Para desativar essas otimizações:

bash

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

Workspaces

O Bun suporta "workspaces" no package.json. Para documentação completa, consulte Package manager > Workspaces.

json

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

Instalando dependências para pacotes específicos

Em um monorepo, você pode instalar as dependências para um subconjunto de pacotes usando a flag --filter.

bash

# Instalar dependências para todos os workspaces exceto `pkg-c`
bun install --filter '!pkg-c'

# Instalar dependências apenas para `pkg-a` em `./packages/pkg-a`
bun install --filter './packages/pkg-a'

Para mais informações sobre filtragem com bun install, consulte Package Manager > Filtering

Substituições e resoluções

O Bun suporta "overrides" do npm e "resolutions" do Yarn no package.json. Estes são mecanismos para especificar um intervalo de versão para metadependências—as dependências das suas dependências. Consulte Package manager > Overrides and resolutions para documentação completa.

json

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

Pacotes globais

Para instalar um pacote globalmente, use a flag -g/--global. Normalmente isso é usado para instalar ferramentas de linha de comando.

bash

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

txt

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

Modo de produção

Para instalar em modo de produção (ou seja, sem devDependencies ou optionalDependencies):

bash

bun install --production

Para instalações reproduzíveis, use --frozen-lockfile. Isso instalará as versões exatas de cada pacote especificadas no lockfile. Se seu package.json discordar do bun.lock, o Bun sairá com um erro. O lockfile não será atualizado.

bash

bun install --frozen-lockfile

Para mais informações sobre o lockfile do Bun bun.lock, consulte Package manager > Lockfile.

Omitindo dependências

Para omitir dependências dev, peer ou opcionais, use a flag --omit.

bash

# Excluir "devDependencies" da instalação. Isso será aplicado ao
# pacote raiz e workspaces se existirem. Dependências transitivas não
# terão "devDependencies".
bun install --omit dev

# Instalar apenas dependências de "dependencies"
bun install --omit=dev --omit=peer --omit=optional

Dry run

Para executar um dry run (ou seja, não instalar nada realmente):

bash

bun install --dry-run

Dependências não-npm

O Bun suporta instalar dependências do Git, GitHub e tarballs hospedados localmente ou remotamente. Para documentação completa, consulte Package manager > Git, GitHub, and tarball dependencies.

json

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

Estratégias de instalação

O Bun suporta duas estratégias de instalação de pacotes que determinam como as dependências são organizadas no node_modules:

Instalações hoisted

A abordagem tradicional do npm/Yarn que achatada dependências em um diretório node_modules compartilhado:

bash

bun install --linker hoisted

Instalações isoladas

Uma abordagem similar ao pnpm que cria isolamento estrito de dependências para prevenir dependências fantasmas:

bash

bun install --linker isolated

Instalações isoladas criam um armazenamento central de pacotes em node_modules/.bun/ com symlinks no node_modules de nível superior. Isso garante que os pacotes só possam acessar suas dependências declaradas.

Estratégia padrão

A estratégia de linker padrão depende se você está começando do zero ou tem um projeto existente:

Novos workspaces/monorepos: isolated (previne dependências fantasmas)
Novos projetos de pacote único: hoisted (comportamento tradicional do npm)
Projetos existentes (feitos antes da v1.3.2): hoisted (preserva compatibilidade com versões anteriores)

O padrão é controlado por um campo configVersion no seu lockfile. Para uma explicação detalhada, veja Package manager > Isolated installs.

Idade mínima de lançamento

Para proteger contra ataques à cadeia de suprimentos onde pacotes maliciosos são publicados rapidamente, você pode configurar um requisito de idade mínima para pacotes npm. Versões de pacotes publicadas mais recentemente que o limite especificado (em segundos) serão filtradas durante a instalação.

bash

# Instalar apenas versões de pacotes publicadas há pelo menos 3 dias
bun add @types/bun --minimum-release-age 259200 # segundos

Você também pode configurar isso no bunfig.toml:

toml

[install]
# Instalar apenas versões de pacotes publicadas há pelo menos 3 dias
minimumReleaseAge = 259200 # segundos

# Excluir pacotes confiáveis da verificação de idade
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Quando o filtro de idade mínima está ativo:

Afeta apenas nova resolução de pacotes - pacotes existentes no bun.lock permanecem inalterados
Todas as dependências (diretas e transitivas) são filtradas para atender ao requisito de idade ao serem resolvidas
Quando versões são bloqueadas pelo filtro de idade, uma verificação de estabilidade detecta padrões de correção de bugs rápidos
- Se várias versões foram publicadas próximas logo após seu filtro de idade, ele estende o filtro para pular essas versões potencialmente instáveis e seleciona uma versão mais antiga e madura
- Pesquisa até 7 dias após o filtro de idade, no entanto, se ainda encontrar lançamentos rápidos, ignora a verificação de estabilidade
- Solicitações de versão exata (como package@1.1.1) ainda respeitam o filtro de idade, mas ignoram a verificação de estabilidade
Versões sem um campo time são tratadas como passando na verificação de idade (o registro npm deve sempre fornecer timestamps)

Para verificação de segurança mais avançada, incluindo integração com serviços e filtragem customizada, veja Package manager > Security Scanner API.

Configuração

Configurando `bun install` com `bunfig.toml`

bunfig.toml é procurado nos seguintes caminhos em bun install, bun remove e bun add:

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

Se ambos forem encontrados, os resultados são mesclados.

Configurar com bunfig.toml é opcional. O Bun tenta ser zero configuração em geral, mas isso nem sempre é possível. O comportamento padrão de bun install pode ser configurado no bunfig.toml. Os valores padrão são mostrados abaixo.

toml

[install]

# se deve instalar optionalDependencies
optional = true

# se deve instalar devDependencies
dev = true

# se deve instalar peerDependencies
peer = true

# equivalente à flag `--production`
production = false

# equivalente à flag `--save-text-lockfile`
saveTextLockfile = false

# equivalente à flag `--frozen-lockfile`
frozenLockfile = false

# equivalente à flag `--dry-run`
dryRun = false

# equivalente à flag `--concurrent-scripts`
concurrentScripts = 16 # (contagem de cpu ou GOMAXPROCS) x2

# estratégia de instalação: "hoisted" ou "isolated"
# padrão depende do configVersion do lockfile e workspaces:
# - configVersion = 1: "isolated" se usando workspaces, caso contrário "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# configuração de idade mínima
minimumReleaseAge = 259200 # segundos
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Configurando com variáveis de ambiente

Variáveis de ambiente têm prioridade mais alta que bunfig.toml.

Nome	Descrição
`BUN_CONFIG_REGISTRY`	Definir um registro npm (padrão: https://registry.npmjs.org)
`BUN_CONFIG_TOKEN`	Definir um token de autenticação (atualmente não faz nada)
`BUN_CONFIG_YARN_LOCKFILE`	Salvar um yarn.lock no estilo Yarn v1
`BUN_CONFIG_LINK_NATIVE_BINS`	Apontar `bin` no package.json para uma dependência específica da plataforma
`BUN_CONFIG_SKIP_SAVE_LOCKFILE`	Não salvar um lockfile
`BUN_CONFIG_SKIP_LOAD_LOCKFILE`	Não carregar um lockfile
`BUN_CONFIG_SKIP_INSTALL_PACKAGES`	Não instalar nenhum pacote

O Bun sempre tenta usar o método de instalação mais rápido disponível para a plataforma alvo. No macOS, é clonefile e no Linux, é hardlink. Você pode alterar qual método de instalação é usado com a flag --backend. Quando indisponível ou com erro, clonefile e hardlink recorrem a uma implementação específica da plataforma de copiar arquivos.

O Bun armazena pacotes instalados do npm em ~/.bun/install/cache/${name}@${version}. Note que se a versão semver tiver uma tag build ou pre, ela é substituída por um hash desse valor. Isso é para reduzir as chances de erros de caminhos de arquivo longos, mas infelizmente complica descobrir onde um pacote foi instalado no disco.

Quando a pasta node_modules existe, antes de instalar, o Bun verifica se o "name" e "version" em package/package.json na pasta node_modules esperada corresponde ao name e version esperados. É assim que determina se deve instalar. Usa um analisador JSON personalizado que para de analisar assim que encontra "name" e "version".

Quando um bun.lock não existe ou package.json alterou dependências, tarballs são baixados e extraídos avidamente durante a resolução.

Quando um bun.lock existe e package.json não mudou, o Bun baixa dependências faltantes preguiçosamente. Se o pacote com um name e version correspondentes já existe no local esperado dentro de node_modules, o Bun não tentará baixar o tarball.

CI/CD

Use a ação oficial oven-sh/setup-bun para instalar bun em um pipeline do GitHub Actions:

yaml

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 ambientes CI/CD que desejam impor builds reproduzíveis, use bun ci para falhar o build se o package.json estiver fora de sincronia com o lockfile:

bash

bun ci

Isso é equivalente a bun install --frozen-lockfile. Instala versões exatas do bun.lock e falha se package.json não corresponder ao lockfile. Para usar bun ci ou bun install --frozen-lockfile, você deve commitar bun.lock ao controle de versão.

E em vez de executar bun install, execute bun ci.

yaml

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

Dependências específicas de plataforma?

O bun armazena valores normalizados de cpu e os do npm no lockfile, junto com os pacotes resolvidos. Ele pula o download, extração e instalação de pacotes desativados para o alvo atual em tempo de execução. Isso significa que o lockfile não mudará entre plataformas/arquiteturas mesmo que os pacotes eventualmente instalados mudem.

Flags `--cpu` e `--os`

Você pode substituir a plataforma alvo para seleção de pacotes:

bash

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

Isso instala pacotes para a plataforma especificada em vez do sistema atual. Útil para builds cross-platform ou ao preparar deployments para ambientes diferentes.

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

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

Peer dependencies?

Peer dependencies são tratadas de forma similar ao yarn. bun install instalará automaticamente peer dependencies. Se a dependência estiver marcada como opcional em peerDependenciesMeta, uma dependência existente será escolhida se possível.

Lockfile

bun.lock é o formato de lockfile do Bun. Veja nosso post do blog sobre o lockfile de texto.

Antes do Bun 1.2, o lockfile era binário e chamado bun.lockb. Lockfiles antigos podem ser atualizados para o novo formato executando bun install --save-text-lockfile --frozen-lockfile --lockfile-only e depois excluindo bun.lockb.

Cache

Para deletar o cache:

bash

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

Backends específicos de plataforma

bun install usa diferentes chamadas de sistema para instalar dependências dependendo da plataforma. Esta é uma otimização de desempenho. Você pode forçar um backend específico com a flag --backend.

hardlink é o backend padrão no Linux. Benchmarking mostrou ser o mais rápido no Linux.

bash

rm -rf node_modules
bun install --backend hardlink

clonefile é o backend padrão no macOS. Benchmarking mostrou ser o mais rápido no macOS. Está disponível apenas no macOS.

bash

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir é similar ao clonefile, exceto que clona cada arquivo individualmente por diretório. Está disponível apenas no macOS e tende a ser mais lento que clonefile. Ao contrário de clonefile, isso não clona recursivamente subdiretórios em uma chamada de sistema.

bash

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile é o fallback usado quando qualquer um dos acima falha, e é o mais lento. no macOS, usa fcopyfile() e no linux usa copy_file_range().

bash

rm -rf node_modules
bun install --backend copyfile

symlink é tipicamente usado apenas para dependências file: (e eventualmente link:) internamente. Para prevenir loops infinitos, ele ignora a criação de link simbólico na pasta node_modules.

Se você instalar com --backend=symlink, o Node.js não resolverá node_modules de dependências a menos que cada dependência tenha sua própria pasta node_modules ou você passe --preserve-symlinks para node ou bun. Veja documentação do Node.js sobre --preserve-symlinks.

bash

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

Metadados do registro npm

O Bun usa um formato binário para cachear respostas do registro NPM. Isso carrega muito mais rápido que JSON e tende a ser menor no disco. Você verá esses arquivos em ~/.bun/install/cache/*.npm. O padrão de nome de arquivo é ${hash(packageName)}.npm. É um hash para que diretórios extras não precisem ser criados para pacotes com escopo.

O uso do Cache-Control do Bun ignora Age. Isso melhora o desempenho, mas significa que o bun pode estar cerca de 5 minutos desatualizado para receber os metadados de versão de pacote mais recentes do npm.

Migração do pnpm

O Bun migra automaticamente projetos do pnpm para o bun. Quando um arquivo pnpm-lock.yaml é detectado e nenhum arquivo bun.lock existe, o Bun migrará automaticamente o lockfile para bun.lock durante a instalação. O arquivo pnpm-lock.yaml original permanece inalterado.

bash

bun install

Nota: A migração só é executada quando bun.lock está ausente. Atualmente não há flag de desativação para migração do pnpm.

O processo de migração lida com:

Migração de lockfile

Converte pnpm-lock.yaml para o formato bun.lock
Preserva versões de pacotes e informações de resolução
Mantém relacionamentos de dependência e peer dependencies
Lida com dependências corrigidas com hashes de integridade

Configuração de workspace

Quando um arquivo pnpm-workspace.yaml existe, o Bun migra configurações de workspace para seu package.json raiz:

yaml

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

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

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

A lista de pacotes do workspace e catálogos são movidos para o campo workspaces no package.json:

json

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

Dependências de catálogo

Dependências usando o protocolo catalog: do pnpm são preservadas:

json

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

Migração de configuração

A seguinte configuração do pnpm é migrada de ambos pnpm-lock.yaml e pnpm-workspace.yaml:

Overrides: Movido de pnpm.overrides para overrides de nível raiz no package.json
Dependências corrigidas: Movido de pnpm.patchedDependencies para patchedDependencies de nível raiz no package.json
Overrides de workspace: Aplicado de pnpm-workspace.yaml para package.json raiz

Requisitos

Requer versão 7 ou superior do lockfile do pnpm
Pacotes do workspace devem ter um campo name em seu package.json
Todas as entradas de catálogo referenciadas por dependências devem existir na definição de catálogos

Após a migração, você pode remover com segurança os arquivos pnpm-lock.yaml e pnpm-workspace.yaml.

Uso básico ​

Para usuários Linux ​

Logging ​

Scripts de ciclo de vida ​

Workspaces ​

Instalando dependências para pacotes específicos ​

Substituições e resoluções ​

Pacotes globais ​

Modo de produção ​

Omitindo dependências ​

Dry run ​

Dependências não-npm ​

Estratégias de instalação ​

Instalações hoisted ​

Instalações isoladas ​

Estratégia padrão ​

Idade mínima de lançamento ​

Configuração ​

Configurando bun install com bunfig.toml ​

Configurando com variáveis de ambiente ​

CI/CD ​

Dependências específicas de plataforma? ​

Flags --cpu e --os ​

Peer dependencies? ​

Lockfile ​

Cache ​

Backends específicos de plataforma ​

Metadados do registro npm ​

Migração do pnpm ​

Migração de lockfile ​

Configuração de workspace ​

Dependências de catálogo ​

Migração de configuração ​

Requisitos ​

Uso básico

Para usuários Linux

Logging

Scripts de ciclo de vida

Workspaces

Instalando dependências para pacotes específicos

Substituições e resoluções

Pacotes globais

Modo de produção

Omitindo dependências

Dry run

Dependências não-npm

Estratégias de instalação

Instalações hoisted

Instalações isoladas

Estratégia padrão

Idade mínima de lançamento

Configuração

Configurando `bun install` com `bunfig.toml`

Configurando com variáveis de ambiente

CI/CD

Dependências específicas de plataforma?

Flags `--cpu` e `--os`

Peer dependencies?

Lockfile

Cache

Backends específicos de plataforma

Metadados do registro npm

Migração do pnpm

Migração de lockfile

Configuração de workspace

Dependências de catálogo

Migração de configuração

Requisitos