Bun packs a runtime, a bundler, a test runner and a package manager into one executable

One executable named bun carries the runtime, the runner and the installer

Bun presents itself as an all-in-one toolkit for JavaScript and TypeScript apps that ships as a single executable called `bun`. Underneath, the runtime is written in Rust and powered by JavaScriptCore, and the project positions it as a drop-in replacement for Node.js. The same binary also implements a test runner, a script runner, and a Node.js-compatible package manager, so the pitch is that a development setup collapses from a large node_modules tree to one command.

TypeScript and JSX run with no separate transpile step. Running a .tsx file directly is one invocation:

bun run index.tsx

Compatibility is not presented as total. Alongside the runtime pages the documentation index carries a page named Node.js compatibility, so compatibility details live in the docs. For a reader weighing the switch, that page matters more than anything in the repository root, because nothing at the top level lists which built-in modules are covered.

curl into bash is the recommended route, and the Docker run unlocks memlock

Five install paths are documented, and they are not variations on one another.

# with install script (recommended)
curl -fsSL https://bun.com/install | bash

# on windows
powershell -c "irm bun.sh/install.ps1 | iex"

# with npm
npm install -g bun

# with Homebrew
brew tap oven-sh/bun
brew install bun

# with Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

The install script is the one the project calls recommended. The Homebrew route needs the tap before the install, so a single brew install line fails on a machine that has never seen oven-sh/bun. The Docker command passes three flags: the container is removed on exit, an init process is added, and the locked-memory limit is set to unlimited rather than left at the default.

That last one has a consequence for CI. The documented pull names the bare `oven/bun` image with no tag, so nothing in this repository tells you how to pin a version inside a container, and a build that follows the command verbatim floats to whatever that tag currently points at.

Linux below kernel 5.1 is out, and an old x64 CPU dies with 'illegal instruction'

Supported platforms are Linux on x64 and arm64, macOS on x64 and Apple Silicon, and Windows on x64 and arm64. Two floors sit under that list.

For Linux, kernel 5.6 or higher is strongly recommended and 5.1 is the minimum. Below 5.1 you are outside what the project supports at all, and the recommendation above the minimum is a separate matter: a kernel in the 5.1 to 5.5 range is allowed and not preferred.

For x64, the documented symptom is an "illegal instruction" error or something similar, with a pointer to the CPU requirements page.

The platform list is also the whole list. The README lists no other platforms.

Every commit to main becomes a canary, and the upgrade flag picks which channel you are on

Upgrading is one command, and the flag decides what you land on:

bun upgrade
bun upgrade --canary

A canary build is released on every commit to main under the canary tag, so the canary channel is not a slow-moving branch. It is whatever the tip of main was when you ran the command.

The tagged releases move quickly underneath that. Bun v1.4.2 came out on 5 September 2026, v1.4.3 on 10 October, and v1.4.4 on 22 October. The last push to main is 2 November 2026, and the repository's own package.json reads version 1.4.4, matching the newest tag.

The consequence for a team is a split between what developers run and what CI runs. A machine upgraded with `bun upgrade --canary` is executing untagged commits, while a pipeline pinning v1.4.4 executes the tagged build from 22 October 2026. Neither command tells you which of the two you are on.

The Cargo workspace lists close to a hundred crates, and Bun builds itself with Bun

The Rust side is a single workspace with members such as src/bundler, src/http, src/sql, src/brotli, src/libuv_sys, src/dns, src/valkey, src/watcher, src/lint/react_compiler and src/install/windows-shim, among roughly a hundred entries in the members list.

The build is driven from package.json rather than from a Makefile, and the profile is a flag:

bun scripts/build.ts --profile=release
bun scripts/build.ts --profile=debug --fuzzilli=on --build-dir=build/debug-fuzz

A bare `bun run build` resolves to the debug profile, so the default build is a debug binary with the sanitizers in place unless you name release yourself. A separate no-asan debug profile exists for the cases where they get in the way. The watch scripts run cargo watch over the workspace, with a Windows variant that targets x86_64-pc-windows-msvc.

The bootstrap cost is real: producing Bun from this repository requires a working Bun to run the build script, so a contributor needs a released binary before the first compile. The JavaScript side of the build pins typescript 6.0.2, esbuild 0.21.5 and prettier 3.9.9.

bun.lock and a separate node-test config put two settings files in one root

The package manager surface is wide: bun install, bun add, bun remove, bun update, bun link, bun pm, bun outdated, bun publish, bun patch, bun why, bun audit, bun info, and bunx for executing a package. The documentation index then breaks the layout into a global cache, a global store, isolated installs, workspaces, catalogs, lockfile, scopes and registries, overrides and resolutions, a security scanner API, and .npmrc.

The repository root shows what that arrangement costs. Alongside bun.lock there are two configuration files, bunfig.toml and bunfig.node-test.toml, sitting next to each other. The purpose of the second file is not stated in source.

Two consequences follow for an existing repository. Migrating rewrites the lockfile into bun.lock, which tooling elsewhere in the pipeline may not read. And registry configuration has two possible homes, since .npmrc is honoured as well as Bun's own settings, so a private registry that worked through npm configuration can behave differently once Bun resolves it.

The README is an index of links, so every capability question leaves the repository

Almost the entire body of the README is a table of contents. It groups Intro, Templating, Runtime, Package manager, Bundler, Test runner, Package runner and API, and under those headings it names `bun init`, `bun create`, Bun.serve for the HTTP server, Bun.build for the bundler, a $ Shell, a REPL, a debugger, watch mode, plugins and macros.

Every one of those entries is a link into the hosted documentation. Nothing here explains what Bun.serve returns, how Bun.build resolves loaders, or how a plugin hook is registered. The repository is a pointer to the specification rather than the specification itself, and the practical effect is that evaluating Bun means leaving the repository for every question that would decide the evaluation.

What the root does contain is contributor tooling: AGENTS.md, CLAUDE.md, REVIEW.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md, plus oxlint.json, clippy.toml, rustfmt.toml, .clang-tidy, rust-toolchain.toml and a .prettierrc. That is a well-served contributor surface and a thin user surface in the same tree.

LICENSE.md is in the root while the repository's license field reads NOASSERTION

The license metadata for this repository comes back as NOASSERTION rather than a named identifier, even though a LICENSE.md file sits at the top level. A compliance pipeline that reads the API field instead of opening the file gets no answer and has to fall back to reading it by hand.

The same gap shows up in versioning. The newest release is v1.4.4 from 22 October 2026, the last push to main is 2 November 2026, and the root package.json reads 1.4.4, so the working tree and the release list currently agree.

For a reader, that combination is the thing to verify before adopting the tool. Confirm the license text yourself rather than the metadata field, and pin a released tag rather than tracking the version string in the repository.

Editorial conclusion

Adopt Bun for a new service or CLI where you control the whole toolchain and can live with checking the Node.js compatibility page per API before you rely on it. Keep Node.js for an existing monorepo whose lockfile, test tooling and CI images are already wired up, since bun.lock, the separate node-test configuration and the unlabelled oven/bun image are all migration work rather than a drop-in swap. Before installing on anything but your laptop, check the kernel version and the CPU flags, because both failure modes surface as an unsupported machine rather than a clear error.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes