This release fixes 287 issues (addressing 324 👍).
To install Bun
curl -fsSL https://bun.sh/install | bash
npm install -g bun
powershell -c "irm bun.sh/install.ps1|iex"
scoop install bun
brew tap oven-sh/bun
brew install bun
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun
To upgrade Bun
bun upgrade
Hoisted installs restored as default
In Bun 1.3.0, we made isolated installs the default for workspaces. While this eliminated phantom dependencies and made installs faster and more predictable, it also introduced some issues for existing monorepos that relied on shared dependencies.
In Bun 1.3.2, Isolated installs are now only the default for new projects, while existing workspaces keep using hoisted installs unless explicitly configured.
To keep using isolated installs in your existing workspaces/monorepos:
[install]
linker = "isolated"
Or use the --linker=isolated
flag:
bun install --linker=isolated
New projects using workspaces (or those without a lockfile) continue to use isolated installs as the default.
configVersion |
Using workspaces? | Default Linker |
|---|---|---|
1 |
✅ | isolated |
1 |
❌ | hoisted |
0 |
✅ | hoisted |
0 |
❌ | hoisted |
Lockfile configVersion
stabilizes install defaults
configVersion
stabilizes install defaultsFlip-flopping between isolated
and hoisted
linker is not good for our users. Collectively, breaking changes are a waste of everyone's time.
To make future bun upgrades easier, bun install
now writes a configVersion
to bun.lock
/ bun.lockb
. This lets us change default configuration in the future without impacting existing projects.
Here's how it works:
New projects: Default toconfigVersion = 1
(v1). In workspaces, v1 uses the isolated linker by default; otherwise it uses hoisted linking.Existing Bun projects: If your existing lockfile doesn't have a version yet, Bun setsconfigVersion = 0
(v0) when you runbun install
, preserving the previous hoisted linker default.Migrations from other package managers:- From pnpm:
configVersion = 1
(v1) - From npm or yarn:
configVersion = 0
(v0)
- From pnpm:
// New projects:
"configVersion": 1,
// Existing projects without a version (after running `bun install`):
"configVersion": 0,
Faster bun install
bun install
Projects that depend on popular libraries like esbuild
or sharp
install faster.
In the next version of Bun
— Jarred Sumner (@jarredsumner)
bun install gets smarter about choosing which & when postinstall scripts run.
In a repo with next.js & vite, bun install gets 6x faster.[pic.twitter.com/tJfJUD0pF9][November 1, 2025]
To disable Bun's built-in defaults via environment variables:
BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 # disables native binlinking
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 # disables script skipping
CPU profiling with --cpu-prof
--cpu-prof
Bun now supports CPU profiling for any script using the --cpu-prof
flag. This records detailed information about how much time your program spends in each function, helping you identify performance bottlenecks and optimize hot paths.
In the next version of Bun
— Jarred Sumner (@jarredsumner)
bun --cpu-prof <script> generates CPU profiles you can open in Chrome DevTools, powered by JavaScriptCore's sampling profiler.[pic.twitter.com/cEPVDfw40S][October 30, 2025]
Profiles are saved in the Chrome DevTools–compatible .cpuprofile
format and can be opened directly in Chrome DevTools (Performance tab) or VS Code's CPU profiler. Sampling runs at 1ms for fine-grained insights.
| Flag | Description |
|---|---|
--cpu-prof |
enables profiling |
--cpu-prof-name <filename> |
sets the output filename |
--cpu-prof-dir <dir> |
sets the output directory |
// script.js
function fib(n) {
return n < 2 ? n : fib(n - 1) + fib(n - 2);
}
console.log(fib(35)); // some CPU work
You can run this script with CPU profiling enabled:
bun --cpu-prof script.js
bun --cpu-prof --cpu-prof-name my-profile.cpuprofile script.js
bun --cpu-prof --cpu-prof-dir ./profiles script.js
Open the generated .cpuprofile
in Chrome DevTools → Performance → Load profile
bun:test
now includes a new onTestFinished(fn)
hook that runs at the very end of a test, after all afterEach
hooks have completed. Use it for cleanup or assertions that must happen after every other per-test hook.
- Runs only inside a test (not in
describe
or preload) - Supports async and done-style callbacks
- Not supported in concurrent tests; use
test.serial
instead or removetest.concurrent
import { test, afterEach, onTestFinished, expect } from "bun:test";
test("runs after afterEach", () => {
const calls = [];
afterEach(() => {
calls.push("afterEach");
});
onTestFinished(() => {
calls.push("onTestFinished");
// afterEach has already run
expect(calls).toEqual(["afterEach", "onTestFinished"]);
});
// test body...
});
test.serial("async cleanup at the very end", async () => {
onTestFinished(async () => {
await new Promise((r) => setTimeout(r, 10));
// ...close DB connections, stop servers, etc.
});
// test body...
});
Thanks to @pfg for the contribution!
ServerWebSocket
subscriptions getter
ServerWebSocket
subscriptions getterServerWebSocket
now includes a subscriptions
getter that returns a de-duplicated list of topics the connection is currently subscribed to.
This makes it easy to inspect and manage per-connection state in pub/sub systems, for example, debugging topic subscriptions or cleaning up resources when clients disconnect.
When a socket closes, subscriptions
automatically returns an empty array.
const server = Bun.serve({
fetch(req, server) {
if (server.upgrade(req)) return;
return new Response("Not a websocket");
},
websocket: {
open(ws) {
ws.subscribe("chat");
ws.subscribe("notifications");
console.log(ws.subscriptions); // ["chat", "notifications"]
ws.unsubscribe("chat");
console.log(ws.subscriptions); // ["notifications"]
},
close(ws) {
console.log(ws.subscriptions); // []
},
},
});
This makes working with Bun's WebSocket pub/sub model more transparent and easier to debug.
Alpine 3.22 in official Docker images
Bun's official Alpine Linux Docker images now use Alpine 3.22 for both x64
and arm64(musl)
builds. This update brings the latest security patches, improved package compatibility, and a smaller base footprint.
Improved Git dependency resolution
bun install
now has better support for npm-style hosted Git URLs and GitHub shorthands.
GitHub repositories specified with custom protocol prefixes are correctly identified and routed through the fast HTTP tarball pathway.
{
"dependencies": {
// GitHub shorthand (now parsed correctly and downloaded via HTTP tarball)
"cool-lib": "github:owner/repo#v1.2.3",
// Different protocols resolve deterministically
"tooling-ssh": "git+ssh://git@github.com/owner/repo.git#main",
"tooling-https": "git+https://github.com/owner/repo.git#main"
}
}
Thanks to @markovejnovic for the contribution!
bun list
alias for bun pm ls
bun list
alias for bun pm ls
You can now list your dependency tree with a shorter, top-level command: bun list
. This is a direct alias for bun pm ls
and supports the same flags (e.g. --all
).
It supports all the same flags—including --all
for a full transitive view, making dependency inspection quicker and easier.
bun list
bun list --all
spawnSync now runs on an isolated event loop
Bun.spawnSync
& child_process.spawnSync
now run on an isolated event loop from the rest of the process, preventing JavaScript timers and microtasks from firing and interfering with the main process's stdin/stdout. This aligns Bun's spawnSync behavior with Node.js and makes timeouts reliable across platforms, including Windows.
This is how it should've been done in the first place. There were several bugs and stability issues with the previous implementation, including cases where using execSync
with vim
would "eat" the first character of keypresses, making it feel very slow to do anything at all.
In rare cases, projects could mistakenly be depending on this behavior. Please let us know if you are negatively impacted by this change.
Node.js compatibility improvements
- Fixed:
EventEmitter
could throw an error whenremoveAllListeners(type)
was called from within an event handler while aremoveListener
meta-listener was registered and the target event had no listeners; behavior now matches Node.js (no error). - Fixed:
ServerResponse.prototype.writableNeedDrain
incorrectly returned true when the response had no handle, causingfs.createReadStream().pipe(res)
and other piped streams to indefinitely in middleware/connect-to-web scenarios (e.g., Vite staticfile serving). Behavior now matches Node.js, allowing streams to flow and readable/end events to fire as expected. - Fixed:
process.mainModule
setter/getter semantics now match Node.js - Fixed: Crash when user code overrides
process.nextTick
. Bun now safely uses the overridden function during internal scheduling (e.g., WebSocket internals) instead of crashing. - Fixed:
Buffer.isEncoding('')
incorrectly returnedtrue
; it now returnsfalse
to match Node.js behavior. - Fixed:
Module._resolveFilename
now forwards the options object (includingoptions.paths
) to overridden implementations and honorsoptions.paths
when provided. This restores compatibility with Node-style require hooks (e.g., Next.js 16) and fixes Next.js 16 + React Compiler + Turbopack builds that previously failed with "Cannot find module './node_modules/babel-plugin-react-compiler'". - Fixed:
Module._resolveFilename
validates thatoptions.paths
is an array and throwsERR_INVALID_ARG_TYPE
otherwise, aligning with Node.js. - Fixed:
process.dlopen
crashed when passed non-object exports (null, undefined, or primitives). Bun now matches Node.js ToObject semantics—throwing TypeError for null/undefined and boxing primitives—preventing segfaults when native addons.
- Fixed: N-API
napi_create_external_buffer
now correctly handles empty inputs (null data and/or length 0) without throwing or creating a detached buffer. When length is 0, it returns a detached ArrayBuffer matching Node.js behavior.napi_get_buffer_info
andnapi_get_arraybuffer_info
correctly report a null pointer and 0 length, andnapi_is_detached_arraybuffer
returns true. This preventsnapi_create_reference
crashes in addons (e.g. ref-napi, ffi-napi, @tdengine/client) and ensures zero-length buffers are created with safe finalization. - Fixed: Crash in N-API when ThreadSafeFunction finalizers or async work deinitialized the environment during dispatch, causing intermittent crashes. Environment references are now safely retained until operations complete, improving reliability for addons using ThreadSafeFunction and finalizers.
- Fixed: N-API property access now returns undefined for missing properties and out-of-bounds elements (e.g.,
napi_get_property
and element getters), matching Node.js behavior. - Fixed: Numeric-string keys (e.g., "0", "42") are handled consistently as index access across N-API property operations (get/has/has_own/delete), aligning semantics with Node.js.
- Fixed:
napi_delete_property
,napi_has_property
, andnapi_has_own_property
now return correct boolean results and propagate exceptions consistently, improving addon compatibility and correctness. - Fixed: Improved error handling across N-API property and element access to avoid spurious failures and improve reliability in native addons.
- Fixed: Importing
better-sqlite3
now fails fast with a clear, actionable error instead of crashing with a dlopen/symbol lookup error (undefined symbol: node_module_register
). The message links to the tracking issue and suggestsbun:sqlite
as an alternative.
- Fixed: Restored use of the system CA trust store for TLS verification, resolving a 1.3.0 regression that caused some HTTPS requests to fail with
UNABLE_TO_GET_ISSUER_CERT_LOCALLY
. Bun now again loads default OS CA paths - Fixed: HTTP server could incorrectly mark a connection as idle after a write failure, leading to a request taking longer to timeout than expected.
- Fixed: Upgrading WebSocket connections via
ws
module in certain cases could consume 100% CPU when it should be idling.
- Fixed: Fetch API methods now reject with
TypeError
instead ofError
when the body has already been consumed (e.g., callingtext()
thenjson()
on the same Request/Response), aligning with the Fetch spec and matching Node/Deno behavior.
- Fixed:
bun:test
lifecycle hooks (beforeAll
,beforeEach
,afterAll
,afterEach
) no longer throw when called with a callback and options as the second argument.(callback, options)
is now correctly parsed, supporting both object and numeric timeouts (e.g., fixes "beforeAll() expects a function as the second argument"). - Fixed:
bun:test
now emits clearer errors when snapshot creation is attempted in CI. Messages explicitly refer to creation (not updating), include the received value, and (for file snapshots) the snapshot name, with guidance to use--update-snapshots
or setCI=false
to override. - Fixed: In rare cases,
bun test
could crash when a test prompted for a sudo password or left a dangling process - Fixed:
expect(...).toThrow
with an async function no longer crashes the test runner when the rejection occurs after the test timeout. The test now times out and reports a failure as expected. - Fixed: bun-types for bun:test incorrectly typed
vi.mock(...)
asvi.module(...)
, causing TypeScript errors ("Property 'mock' does not exist") and potential runtime TypeError.vi.mock
is now correctly typed.
- Fixed: 2 different sourcemap sorting bugs. Please continue letting us know if you run into sourcemap-related issues.
- Fixed: CSS view-transition pseudo-elements now support class selector arguments (e.g.,
::view-transition-old(.slide-out)
,::view-transition-new(.fade-in)
,::view-transition-group(.card)
,::view-transition-image-pair(.hero)
), resolving "Unexpected token: ." errors during parsing/bundling. These selectors now parse, minify, and serialize correctly. - Fixed: CSS minifier now processes
@layer
blocks, ensuringcolor-scheme
rules receive the required--buncss-light
/--buncss-dark
variable injections andprefers-color-scheme
fallbacks for browsers withoutlight-dark()
support.
- Fixed:
bun update --interactive
(including--latest
) updatedpackage.json
but did not install the selected updates. It now installs the updated dependencies and refreshesnode_modules
, so no extrabun install
is required. - Fixed:
bun update --interactive
no longer stripsnpm:
alias prefixes when updating dependencies inpackage.json
. Aliases and range operators are preserved when bumping versions (e.g.,npm:@jsr/std__semver@1.0.5 → npm:@jsr/std__semver@1.0.6
,npm:@types/no-deps@^1.0.0 → npm:@types/no-deps@^2.0.0
). - Fixed:
bun install
left optional peerDependencies unresolved in isolated installs, causing inconsistent peer resolutions, duplicate package copies innode_modules/.bun
, and TypeScript type incompatibilities in monorepos (e.g. Elysia + plugins). Optional peers now resolve to an installed package when available, improving deduplication and linker behavior. - Fixed:
bun install
no longer conflatesgit+ssh
andgit+https
(or other protocol prefixes) references to the same repository; each specifier is resolved and recorded independently. - Fixed: GitHub dependencies with custom protocol prefixes (e.g., git+https://github.com/owner/repo#v1.2.3) are now recognized as GitHub tag downloads, enabling the faster HTTP download path and reducing install time. Improved recognition of GitHub shorthand (owner/repo and owner/repo#branch) during dependency resolution increases reliability for hosted git installs.
- Fixed: Global
~/.bunfig.toml
could be loaded more than once in a single run, leading to duplicate configuration application and unexpected behavior. Bun now guarantees the config is loaded at most once per run. - Fixed: Crash when parsing MySQL OK packets with truncated or empty payloads. An integer underflow could produce an oversized read and trigger an overflow panic. Remaining bytes are now safely clamped, improving reliability when handling minimal responses (e.g., queries that return no rows).
- Fixed: A crash in
Bun.CookieMap#delete
in certain cases. - Fixed: ANSI color support is now detected per stream (stdout vs stderr). This resolves missing colors in errors/crash reports and test diffs, and prevents misrendered box-drawing characters in interactive commands (e.g., publish, outdated, create, init, update) when the terminal doesn't support color.
- Fixed: Interactive UIs and installer output only use box-drawing characters when stdout supports ANSI, avoiding garbled tables and lines in plain terminals.
- Fixed: Hot reload terminal-clearing logic respects stdout color capability, avoiding unnecessary escape sequences in non-ANSI environments.
- Fixed: Test framework output (expect diffs and matcher messages) consistently respects stderr color support for readable failure output.
- Fixed: Crash reports on glibc-based Linux could show severely truncated stack traces (sometimes only the signal handler frame). Bun now uses Zig's
std.debug.captureStackTrace
for more complete traces, falling back to glibcbacktrace()
when it provides more frames (e.g., on some ARM systems).
- Fixed: Requiring an ES module with top‑level await via
require()
orimport.meta.require
would throw and leave a partially initialized module in the cache, causing subsequentimport()
orrequire()
to behave incorrectly. The failed module is now evicted from the cache on error so a later dynamicimport()
loads and evaluates it correctly.
- Fixed: TypeScript types for Blob, ReadableStream, and Response now include
text()
,bytes()
,json()
,formData()
, andarrayBuffer()
convenience methods, resolving errors like "Type 'Blob' is missing ... json, formData" when usingresponse.blob()
. - Fixed: TypeScript definitions for
Bun.spawn
andspawnSync
now include missing options and match runtime behavior. You can usedetached
,onDisconnect
(fires when the IPC channel closes), andlazy
(defer stdout/stderr reads until accessed). Also clarified IPC lifecycle ordering withonExit
. - Fixed: spawn/spawnSync option shapes are unified via
Bun.Spawn.BaseOptions
in the types; the olderSpawn.OptionsObject
alias is deprecated. UseBaseOptions
or the specific spawn/spawnSync option types going forward.
- Fixed: Web Crypto
crypto.exportKey("jwk")
for EC private keys sometimes produced a shorter-than-required "d" parameter (missing leading-zero padding), violating RFC 7518 and causing import failures in Chrome. Bun now pads "d" to the correct length for P-256 (32 bytes), P-384 (48 bytes), and P-521 (66 bytes).