bun run --bun: run package scripts and CLIs with Bun instead of Node.js

bun run --bun <script> forces package scripts and executables from node_modules/.bin to run on the Bun runtime. Without the flag, bun run is only a fast script runner: a script that calls node, or a CLI whose file starts with #!/usr/bin/env node (vite, next, eslint, tsc…), still runs on Node.js if it is installed. With --bun, Bun puts a temporary node on PATH that points to itself, so those commands run in Bun.

Same script, two runtimes

typeof Bun is "object" inside Bun and "undefined" in Node.js:

cat > package.json <<'EOF'
{
  "name": "demo",
  "scripts": { "which": "node -p \"typeof Bun\"" }
}
EOF
echo "--- bun run which"
npx --yes bun@1 run which 2>/dev/null
echo "--- bun run --bun which"
npx --yes bun@1 run --bun which 2>/dev/null

--- bun run which
undefined
--- bun run --bun which
object

The script text says node in both cases. Only the second run executes it in Bun, because --bun redirects the node command.

Where to put the flag

The flag must come before the script name. In bun run dev --bun, the text --bun is passed to the script as an argument instead.

bunfig.toml

[run]
# behave as if --bun were always passed
bun = true

This is handy for projects that are fully Bun-based, such as an Elysia or Hono server built with Vite: every bun run uses one runtime without repeating the flag.

When not to use it

• Tools that rely on Node.js internals Bun does not implement yet may crash or behave differently. If a CLI fails only with --bun, run it without the flag.
• Machines without Node.js: here bun run already falls back to Bun when no node binary exists, so the flag changes nothing.
• Speed: Bun starts faster, but a long build is dominated by the tool's own work, so the gain is usually small.

Related

A script that does not exist fails with Script not found. Running TypeScript files directly is covered in run a TypeScript file with Bun; type errors are not checked in either case.

FAQ