O que é bunx e quando usá-lo

bunx é o executor de pacotes do Bun e um alias para bun x; ele baixa e executa o binário de um pacote do npm sem uma instalação global, cumprindo a mesma função que o npx e o yarn dlx.

Se você já ficou esperando o npx inicializar um comando de scaffold que executa dezenas de vezes por dia, esse pequeno atraso é exatamente o que o bunx foi criado para eliminar. Se você já digita npx create-next-app ou npx shadcn@latest diariamente, o bunx é o substituto quase imediato que você passa a usar assim que o Bun estiver instalado na sua máquina — com uma ressalva de runtime (--bun) e um ponto de atenção real (ferramentas que fixam literalmente a string npx) que vale entender antes de migrar.

Este artigo apresenta o modelo mental: o que é o bunx, como ele resolve pacotes, por que inicializa mais rápido que o npx, o que a flag --bun realmente faz e uma regra de decisão para saber quando usá-lo.

O que é bunx?

bunx executa um binário de um pacote npm sem instalá-lo globalmente, e já vem incluído automaticamente com o Bun. A documentação confirma que bunx é um alias para bun x e é instalado automaticamente quando você instala o bun. É o equivalente do npx ou do yarn dlx no ecossistema Bun.

A sintaxe de invocação é idêntica à do npx:

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

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

Os pacotes declaram seus binários no campo "bin" do package.json; bunx <pacote> localiza esse binário e o executa. O versionamento funciona da mesma forma que no npx. Basta acrescentar @versão ao nome do pacote:

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

Quando o nome do binário difere do nome do pacote, use -p/--package para especificar o pacote explicitamente, seguido do binário:

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

Como o bunx resolve um pacote?

O bunx verifica primeiro se há uma cópia local do pacote instalada, e só então faz a instalação automática a partir do npm, armazenando o que instala no cache global do Bun para reutilização posterior. Esse é o comportamento documentado: “Assim como o npx, o bunx verifica primeiro se há um pacote instalado localmente e, caso contrário, faz a instalação automática a partir do npm.” Os pacotes resolvidos ficam no cache global do Bun, de modo que execuções subsequentes ignoram o download.

Vale fazer uma correção importante: o npx moderno (npm v7+, ou seja, npm exec) não baixa e descarta o pacote a cada execução. Ele também mantém um cache persistente por usuário e reutiliza os pacotes em invocações repetidas. Portanto, a diferença real não é “npx descarta, bunx mantém”; ambos fazem cache. O diferencial genuíno está em onde o cache reside (no armazenamento global próprio do Bun) e no overhead de runtime entre a invocação e a execução.

Por que o bunx é mais rápido que o npx

O bunx inicializa mais rápido porque roda no runtime do Bun, que é construído sobre o JavaScriptCore (a engine do Safari), em vez de inicializar o Node — portanto, o custo fixo de lançar o executor de pacotes é menor. A equipe do Bun apresenta o ganho de forma concreta: a introdução do bunx o descreveu como capaz de instalar e executar um binário do npm 100x mais rápido que o npx, um número que a documentação associa especificamente a pacotes já instalados localmente.

Trate esse número como a afirmação publicada pelo Bun para o caso aquecido, com o pacote já instalado — não como um benchmark universal. O argumento sobre inicialização é o que se generaliza: para uma invocação de CLI com cache frio (o que você faz dezenas de vezes por dia ao fazer scaffold de projetos), o menor overhead de lançamento de processo do Bun é onde o tempo é recuperado. Para uma primeira instalação que precisa acessar a rede, ambas as ferramentas pagam o custo do download, e qualquer diferença de velocidade se reduz à taxa de instalação mais o delta de inicialização, e não a uma diferença de 100x.

Se quiser um número em que possa confiar, meça você mesmo e separe as execuções com cache frio das com cache aquecido:

# cache aquecido (ambos já resolvidos) vs frio — meça, não assuma
hyperfine 'npx cowsay hi' 'bunx cowsay hi'

A Flag —bun

A flag --bun força uma CLI como Vite, Next ou Prisma a ser executada no runtime do Bun em vez do Node, sobrescrevendo o shebang #!/usr/bin/env node com o qual a ferramenta normalmente é distribuída. Por padrão, o Bun respeita esse shebang e inicializa um processo node para executar o arquivo; --bun instrui o Bun a usar seu próprio runtime:

bunx --bun vite dev

A flag é sensível à posição. Ela deve aparecer antes do nome do executável. Tudo que vier após o nome é repassado diretamente à ferramenta como argumento próprio:

bunx --bun my-cli   # correto — executa my-cli no Bun
bunx my-cli --bun   # incorreto — passa --bun para my-cli

Use --bun quando quiser de fato que a ferramenta rode no Bun, para aproveitar a inicialização mais rápida ou o suporte nativo a TypeScript. Omita-a (comportamento padrão) quando uma ferramenta depender de comportamentos específicos do Node; algumas ferramentas de build e CLIs pressupõem internals do Node, e forçá-las no runtime do Bun pode gerar falhas de compatibilidade. Na prática, um modo de falha comum é uma CLI que funciona normalmente com bunx toolname mas lança erros quando --bun troca o runtime por baixo dela. A solução geralmente é remover --bun e deixar o shebang do Node prevalecer.

Quando usar bunx (e quando manter o npx)

Regra de decisão: use bunx para scaffolding pontual e ferramentas CLI (bunx create-next-app my-app, bunx prisma migrate, bunx prettier foo.js) e mantenha o npx apenas quando algo fixar literalmente a string npx ou apresentar incompatibilidades com o runtime do Bun.

O único ponto de atenção real são ferramentas que chamam npx pelo nome. Um alias de shell como alias npx=bunx funciona quando você digita comandos de forma interativa, mas aliases de shell existem apenas em shells interativos: são invisíveis para execuções não interativas. Uma ferramenta que chama npx internamente (por exemplo, uv run invocando-o internamente) não verá o alias de forma alguma.

A solução é colocar um executável real chamado npx no seu PATH, de modo que qualquer processo que inicialize npx resolva para o seu shim. O contorno do htdocs tem apenas três linhas:

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

Certifique-se de que ~/.local/bin apareça no início do seu PATH. Por ser um arquivo real em disco, e não um alias de shell, execuções não interativas também o resolverão. Se quiser um fallback que roteie pelo Bun apenas quando ele estiver instalado, uma função wrapper condicional com uma saída de emergência --real, conforme demonstrado por nrjdalal, é a versão mais elaborada da mesma ideia.

Conclusão

Trate o bunx como o npx em um runtime mais rápido: mesma ordem de resolução, mesma sintaxe de versionamento, mesmo formato de comando, com uma inicialização de menor overhead e pacotes armazenados no cache próprio do Bun. Adicione a flag --bun apenas quando quiser que a própria ferramenta rode no Bun, mantenha-a antes do nome do executável e coloque um shim real de npx no seu PATH para as poucas ferramentas que exigem o comando literal. Instale o Bun, substitua um npx por bunx no seu próximo scaffold e meça a diferença você mesmo.

Perguntas Frequentes

bunx é um substituto direto do npx?

bunx é um substituto quase direto do npx: compartilha o mesmo formato de comando, a mesma sintaxe de versionamento com o sufixo @versão e a mesma ordem de resolução com prioridade local. A exceção são ferramentas ou scripts que chamam internamente a string literal npx, que não reconhecerão o bunx a menos que você coloque um executável real chamado npx no seu PATH. Nesses casos, o bunx não é substituído automaticamente.

bunx funciona sem instalar o Bun separadamente?

Não, o bunx requer o Bun. bunx é um alias para o comando bun x e é instalado automaticamente sempre que você instala o próprio Bun, portanto não existe um pacote bunx independente. Uma vez que o Bun esteja na sua máquina, o bunx fica disponível sem nenhuma configuração adicional. Se o Bun não estiver instalado, o comando bunx não existe e você deve recorrer ao npx ou a outro executor de pacotes.

Qual é a diferença entre bun x e bunx?

Não há diferença funcional: bunx é simplesmente um alias para bun x, portanto os dois comandos são executados de forma idêntica. Ambos invocam o executor de pacotes do Bun para executar o binário de um pacote sem instalação global. Use a forma que preferir. bunx existe principalmente como uma forma mais curta e familiar ao npx, que desenvolvedores vindos do npm reconhecem imediatamente.

Por que bunx --bun quebra algumas CLIs que funcionam normalmente sem ele?

Porque --bun força a CLI a rodar no runtime do Bun em vez do Node, sobrescrevendo o shebang do Node com o qual a ferramenta é distribuída. Algumas ferramentas de build e CLIs dependem de internals específicos do Node, portanto trocar o runtime expõe falhas de compatibilidade. Uma ferramenta que funciona com bunx toolname simples pode lançar erros assim que --bun é adicionado. A solução é remover --bun e deixar a ferramenta rodar no Node conforme seu shebang determina.