Qué es bunx y cuándo usarlo

bunx es el ejecutor de paquetes de Bun y un alias de bun x; descarga y ejecuta el binario de un paquete desde npm sin necesidad de una instalación global, la misma función que cumplen npx y yarn dlx.

Si alguna vez has esperado a que npx arranque un comando de scaffolding que ejecutas decenas de veces al día, ese pequeño retraso es exactamente lo que bunx pretende eliminar. Si ya escribes npx create-next-app o npx shadcn@latest a diario, bunx es el sustituto casi directo al que recurrirás una vez que tengas Bun instalado, con una particularidad de runtime (--bun) y una trampa real (herramientas que tienen codificada la cadena literal npx) que conviene entender antes de hacer el cambio.

Este artículo te ofrece el modelo mental: qué es bunx, cómo resuelve paquetes, por qué arranca más rápido que npx, qué hace realmente el flag --bun y una regla de decisión para saber cuándo usarlo.

¿Qué es bunx?

bunx ejecuta un binario de un paquete npm sin instalarlo globalmente, y se incluye automáticamente con Bun. La documentación confirma que bunx es un alias de bun x y se instala automáticamente al instalar bun. Es el equivalente en Bun de npx o yarn dlx.

La sintaxis de invocación es idéntica a la de npx:

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

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

Los paquetes declaran sus binarios en el campo "bin" de package.json; bunx <paquete> localiza ese binario y lo ejecuta. El anclaje de versiones funciona igual que en npx: basta con añadir @versión al nombre del paquete:

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

Cuando el nombre del binario difiere del nombre del paquete, usa -p/--package para especificar el paquete de forma explícita y luego el binario:

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

¿Cómo resuelve bunx un paquete?

bunx comprueba primero si existe una copia del paquete instalada localmente, y si no la encuentra, recurre a la instalación automática desde npm; lo que instala queda almacenado en la caché global de Bun para reutilizarlo en ejecuciones posteriores. Este comportamiento está documentado: “Al igual que con npx, bunx comprueba primero si hay un paquete instalado localmente y, en caso contrario, recurre a la instalación automática desde npm.” Los paquetes resueltos se almacenan en la caché global de Bun, de modo que las ejecuciones posteriores omiten la descarga.

Vale la pena aclarar un malentendido frecuente: el npx moderno (npm v7+, es decir, npm exec) no descarga y descarta el paquete en cada ejecución. También mantiene una caché persistente por usuario y reutiliza los paquetes en invocaciones repetidas. Por tanto, la diferencia real no es “npx descarta, bunx conserva”; ambos cachean. El verdadero diferenciador es dónde reside la caché (el almacén global propio de Bun) y la sobrecarga de runtime desde la invocación hasta la ejecución.

Por qué bunx es más rápido que npx

bunx arranca más rápido porque corre sobre el runtime de Bun, que está construido sobre JavaScriptCore (el motor de Safari) en lugar de levantar Node, por lo que el coste fijo de lanzar el ejecutor de paquetes es menor. El equipo de Bun cuantifica la mejora de forma concreta: la introducción de bunx lo presentó como capaz de instalar y ejecutar un binario desde npm 100 veces más rápido que npx, una cifra que la documentación asocia específicamente a los paquetes ya instalados localmente.

Toma ese número como la cifra publicada por Bun para el caso en caliente, con el paquete ya instalado, no como un benchmark universal. Lo que sí se generaliza es la historia del arranque: para una invocación CLI en frío (lo que haces decenas de veces al día al hacer scaffolding de proyectos), la menor sobrecarga de lanzamiento de procesos de Bun es donde se recupera el tiempo. Para una primera instalación que requiere acceder a la red, ambas herramientas pagan el coste de la descarga, y cualquier diferencia de velocidad se reduce al rendimiento de instalación más ese delta de arranque, no a una brecha de 100x.

Si quieres un número en el que puedas confiar, mídelo tú mismo y separa las ejecuciones con caché fría de las que tienen caché caliente:

# caché caliente (ambos ya resueltos) vs. fría — mide, no asumas
hyperfine 'npx cowsay hi' 'bunx cowsay hi'

El flag —bun

El flag --bun fuerza a una CLI como Vite, Next o Prisma a ejecutarse sobre el runtime de Bun en lugar de Node, anulando el shebang #!/usr/bin/env node con el que normalmente se distribuye la herramienta. Por defecto, Bun respeta ese shebang y lanza un proceso node para ejecutar el archivo; --bun le indica que use el runtime de Bun en su lugar:

bunx --bun vite dev

El flag es sensible a la posición. Debe aparecer antes del nombre del ejecutable. Todo lo que venga después del nombre se pasa directamente a la herramienta como argumento propio:

bunx --bun my-cli   # correcto — ejecuta my-cli sobre Bun
bunx my-cli --bun   # incorrecto — pasa --bun a my-cli

Usa --bun cuando realmente quieras que la herramienta corra sobre Bun, para aprovechar su arranque más rápido o su manejo nativo de TypeScript. Omítelo (comportamiento por defecto) cuando una herramienta dependa de comportamientos específicos de Node; algunas herramientas de build y CLIs asumen las interioridades de Node, y forzarlas al runtime de Bun puede provocar fallos de compatibilidad. En la práctica, un modo de fallo habitual es una CLI que funciona con bunx toolname pero falla en cuanto --bun cambia el runtime por debajo. La solución suele ser eliminar --bun y dejar que el shebang de Node prevalezca.

Cuándo usar bunx (y cuándo quedarse con npx)

Regla de decisión: usa bunx para scaffolding puntual y herramientas CLI (bunx create-next-app my-app, bunx prisma migrate, bunx prettier foo.js) y mantén npx solo cuando alguna herramienta tenga codificada la cadena literal npx o falle sobre el runtime de Bun.

La única trampa real son las herramientas que llaman a npx por su nombre. Un alias de shell como alias npx=bunx funciona cuando escribes comandos de forma interactiva, pero los aliases de shell solo existen en shells interactivos: son invisibles para los procesos lanzados de forma no interactiva. Una herramienta que invoca npx internamente (por ejemplo, uv run llamándolo desde dentro) no verá el alias en absoluto.

La solución es colocar un ejecutable real llamado npx en tu PATH para que cualquier proceso que lance npx resuelva a tu shim. La solución de htdocs son tres líneas:

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

Asegúrate de que ~/.local/bin aparezca al principio de tu PATH. Al ser un archivo real en disco y no un alias de shell, los procesos no interactivos también lo resuelven. Si prefieres un mecanismo de respaldo que solo enrute a través de Bun cuando esté instalado, una función wrapper condicional con una vía de escape --real, como muestra nrjdalal, es la variante más elaborada de la misma idea.

Conclusión

Considera bunx como npx sobre un runtime más rápido: mismo orden de resolución, misma sintaxis de anclaje de versiones, misma forma de los comandos, con un arranque de menor sobrecarga y los paquetes cacheados en el almacén propio de Bun. Añade el flag --bun solo cuando quieras que la herramienta en sí corra sobre Bun, mantenlo antes del nombre del ejecutable, y coloca un shim real de npx en tu PATH para el puñado de herramientas que exigen el comando literal. Instala Bun, sustituye un npx por bunx en tu próximo scaffold y mide la diferencia tú mismo.

Preguntas frecuentes

¿Es bunx un reemplazo directo de npx?

bunx es un reemplazo casi directo de npx: comparte la misma forma de comandos, la misma sintaxis de anclaje de versiones con el sufijo @versión y el mismo orden de resolución con preferencia local. La única excepción son las herramientas o scripts que invocan internamente la cadena literal npx, que no reconocerán bunx a menos que coloques un ejecutable real llamado npx en tu PATH. En esos casos, bunx no se sustituye de forma automática.

¿Funciona bunx sin instalar Bun por separado?

No, bunx requiere Bun. bunx es un alias del comando bun x y se instala automáticamente al instalar el propio Bun, por lo que no existe un paquete bunx independiente. Una vez que Bun está en tu máquina, bunx está disponible sin ninguna configuración adicional. Si Bun no está instalado, el comando bunx no existe y debes recurrir a npx u otro ejecutor de paquetes.

¿Cuál es la diferencia entre bun x y bunx?

No hay ninguna diferencia funcional: bunx es simplemente un alias de bun x, por lo que ambos comandos se ejecutan de forma idéntica. Los dos invocan el ejecutor de paquetes de Bun para ejecutar el binario de un paquete sin instalación global. Usa la forma que prefieras. bunx existe principalmente como una forma más corta y familiar para los desarrolladores que vienen de npm y reconocen npx de inmediato.

¿Por qué bunx --bun rompe algunas CLIs que funcionan bien sin ese flag?

Porque --bun fuerza a la CLI a ejecutarse sobre el runtime de Bun en lugar de Node, anulando el shebang de Node con el que se distribuye la herramienta. Algunas herramientas de build y CLIs dependen de las interioridades específicas de Node, por lo que cambiar el runtime provoca fallos de compatibilidad. Una herramienta que funciona con bunx toolname puede fallar en cuanto se añade --bun. La solución es eliminar --bun y dejar que la herramienta corra sobre Node tal como indica su shebang.