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

> One Rust binary on top of JavaScriptCore runs TypeScript directly, replaces npm, and carries its own bundler and test runner. The install has a kernel floor, and building from source needs Bun already on the machine.

**oven-sh/bun** — A fast JavaScript runtime, bundler, test runner and package manager.

- Repository: https://github.com/oven-sh/bun
- Website: https://bun.com
- Stars: 96,029 · Forks: 5,056
- Language: Rust
- License: not declared
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/oven-sh-bun

## 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:

```bash
bun run index.tsx
```

Compatibility is not presented as total. Alongside the runtime pages the documentation index carries a page named Node.js compatibility and another named Auto-install, which is the project's way of saying gaps get looked up per API rather than assumed away. 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.

```sh
# 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, which means an old corporate or container host can run Bun without any obvious sign that it is running an unadvised configuration.

For x64, the documented symptom is an "illegal instruction" error or something similar, with a pointer to the CPU requirements page. That failure arrives before the runtime prints anything, and the message names a CPU instruction rather than the tool, so the first reaction tends to be a wrong one. Neither the kernel floor nor the CPU requirement is visible from `bun --version`.

The platform list is also the whole list. There is no 32-bit target and no FreeBSD target, and the Windows arm64 build has no package manager route above, since the Homebrew path is macOS only.

## 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:

```sh
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 came out on 20 August 2026, v1.4.1 on 4 September, and v1.4.2 on 5 September, two patch releases one day apart. The last push to main is 24 September 2026, and the repository's own package.json already reads version 1.4.3, which means work exists on main that no release tag carries.

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.2 executes a build three weeks older. 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/jsc, src/bundler, src/http, src/sql, src/boringssl, src/brotli, src/zstd, src/mimalloc_sys, src/libuv_sys, src/dns, src/uws, src/lsquic_sys, src/valkey, src/watcher, src/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:

```bash
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, oxlint 1.70.0 and prettier 3.6.2.

## 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. One config for Bun's own test runner and one for running a Node test suite under Bun is a deliberate split, and it is the clearest sign that adopting the test runner is a separate decision from adopting the runtime.

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.2 from 5 September 2026, the last push to main is 24 September 2026, and the root package.json has moved to 1.4.3 without a matching tag. Two separate signals, the published release list and the version in the working tree, describe the same project at different points, and neither is marked as the one to trust.

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, since the version string runs ahead of what has shipped.

## 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.

## FAQ

### What is oven sh bun?

It is a single executable called bun that combines a JavaScript and TypeScript runtime, a bundler, a test runner, a script runner and a Node.js-compatible package manager. The runtime is written in Rust and powered by JavaScriptCore.

### What is bun TypeScript?

Bun runs TypeScript and JSX directly with no separate transpile step, so a .tsx file runs as written. The documentation index also carries dedicated TypeScript and TypeScript 6 pages, and the repository's own devDependencies pin typescript 6.0.2.

### What is the current version of bun?

The newest tagged release listed is Bun v1.4.2, published on 5 September 2026, after v1.4.1 on 4 September and v1.4 on 20 August 2026. The last push to main is 24 September 2026 and the root package.json reads 1.4.3.

### Which is better, bun or NPM?

Bun's package manager is Node.js-compatible and replaces a node_modules tree with the single bun executable, and installing it through npm with npm install -g bun is one of the documented routes. The compatibility documentation page is where the remaining gaps are recorded.

### What is the difference between bun and Vite?

The project does not frame itself against Vite. Its bundler is reached through Bun.build, and the documentation index lists loaders, plugins, macros, a single-file executable target, CSS, hot module replacement and a page comparing it to esbuild.

## Sources

- [Official documentation](https://bun.com)
- [Official README](https://github.com/oven-sh/bun#readme)
- [Project repository](https://github.com/oven-sh/bun)
- [Release notes](https://github.com/oven-sh/bun/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oven-sh-bun