bunx

Active contributors: Jarred Sumner, Dylan Conway

bunx <pkg> (also reachable as bun x <pkg>) executes a package's binary, downloading it on the fly if necessary. The implementation is src/cli/bunx_command.zig (~43 KB).

Purpose

A drop-in replacement for npx and pnpm dlx:

• Runs <pkg>'s declared bin entry without manually installing it into node_modules.
• Caches packages in a global cache so subsequent runs are instant.
• Supports bunx <scope>/<pkg>, bunx <pkg>@<tag>, bunx <gitspec>, and bunx -- to pass args through.

Pipeline

graph TD
    User["bunx eslint --fix"] --> Parse[parse package + bin]
    Parse --> Local{exists in node_modules?}
    Local -->|yes| Run
    Local -->|no| Cache{cached globally?}
    Cache -->|yes| Run
    Cache -->|no| Install[install into ~/.bun/install/cache + global tempdir]
    Install --> Run[exec bin via runtime/run_command]

The "global cache" is ~/.bun/install/cache/ shared with bun install. Bunx never installs into the project's node_modules/ unless asked.

How it picks the binary

1. Parse <pkg>. Strip @scope/ and version suffix.
2. Resolve to a manifest via the npm registry (or the local cache if up-to-date).
3. Read the manifest's bin field. If it has a single binary, that's the binary. If multiple, pick the one matching the package name (or an explicit --package=<pkg> flag).
4. Look up the entry path inside the tarball. Extract if needed.
5. Spawn the entry via the same machinery as bun run: detect if it's a JS file (run inside the current Bun process via the runtime) or a native binary (exec it).

CLI surface

bunx prettier --write .
bunx eslint@latest --fix .
bunx --bun create-vite my-app
bunx -- ts-node script.ts
bunx jest --runInBand

bunx <pkg> reuses Bun's runtime for JS-file binaries, so bunx tsc runs tsc inside Bun rather than spawning Node. bunx --node <pkg> forces Node compatibility mode (an emulation layer that simulates a Node environment for packages that don't work under Bun yet).

Implementation notes

• HTTP fetches go through src/install/NetworkTask.zig and ultimately src/http/HTTPThread.zig.
• Tarball extraction reuses src/install/extract_tarball.zig and TarballStream.zig.
• The "is this an upgrade vs cache hit" decision is in bunx_command.zig — it consults the on-disk manifest cache TTL and bumps the cache if --force is set.
• Per-shell completions are produced by src/cli/install_completions_command.zig.

Entry points for modification

• To change package selection (e.g. add a new shorthand syntax), edit the parser at the top of src/cli/bunx_command.zig.
• To change cache behaviour, look at bunx_command.zig's cache_hit path and the underlying src/install/PackageManager.zig cache.

Key source files

File	Purpose
src/cli/bunx_command.zig	The full implementation.
src/install/NetworkTask.zig	Async fetch.
src/install/extract_tarball.zig	Tarball extraction.
src/cli/install_completions_command.zig	Shell completions.