Bun Package Manager: Complete Guide vs NPM, Yarn & PNPM

Bun is a JavaScript runtime and package manager built from scratch with Zig and JavaScriptCore. It aims to be a drop-in replacement for NPM, Yarn, and PNPM with significantly faster install times and a simpler toolchain. Since this article was first published in February 2024, Bun has gained full Windows support, a new text-based lockfile, and was acquired by Anthropic in December 2025.

Why switch to Bun: bun vs npm, yarn & pnpm compared

The core argument for switching is speed. Bun installs packages in parallel using multiple threads, caches results globally, and can be up to 30x faster than npm on cold installs. On warm installs (cache populated, lockfile present), the difference is even wider.

But speed is not the only reason. Here’s what you get:

Speed comparison: npm vs pnpm vs Bun

Bun’s own benchmarks claim “up to 30x faster” installs than npm. That number is from their marketing, not an independent source. In practice, the gap depends on your project size, network, and cache state.

The pnpm.io/benchmarks page (daily-updated) compares npm, pnpm, Yarn Classic, and Yarn PnP, but does not include Bun. For npm vs pnpm, the benchmark shows pnpm is roughly 2-3x faster than npm on clean installs. Bun’s real-world advantage over npm is typically 5-15x, depending on the scenario.

Your results will vary. Test on your own project. See the real-world benchmark below for one data point.

When this article was first published, some developers questioned Bun’s long-term viability, drawing parallels with Yarn’s rise and fall. The Anthropic acquisition in December 2025 has largely settled that debate. Bun is no longer a side project. It’s the runtime behind Claude Code.

You can check how to migrate Astro to Bun on CloudFlare for a real migration walkthrough.

How to install Bun on macOS, Linux & Windows

Bun installs on all major platforms. Below are the current recommended methods.

brew install oven-sh/bun/bun

curl -fsSL https://bun.sh/install | bash

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

npm install -g bun

Verify installation

bun --version
# Should print something like: 1.3.14

bun --revision
# Prints the build revision (useful for bug reports)

To self-update Bun:

bun upgrade

If bun is not found after install, make sure ~/.bun/bin is in your PATH. Add this to your shell config:

# bash/zsh, add to ~/.bashrc or ~/.zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

For Fish shell, see best Fish shell plugins and tools for PATH setup guidance.

If you need Node.js installed alongside Bun, see how to install Node.js using NVM.

Bun lockfile: bun.lock vs bun.lockb

Before Bun 1.2 (January 2025), the default lockfile was the binary bun.lockb. It worked, but you couldn’t diff it in git, couldn’t review lockfile changes in PRs, and merge conflicts were impossible to resolve by hand.

Bun 1.2 made bun.lock the default. It’s a text-based JSONC file that diffs and merges like any other source file.

bun install --save-text-lockfile --frozen-lockfile --lockfile-only
# Then remove the old binary lockfile
rm bun.lockb

Verify: ls bun.lock should exist. Run git diff bun.lock. You should see readable JSONC output.

If bun install still generates bun.lockb instead of bun.lock, check bunfig.toml for saveTextLockfile = false or upgrade your Bun version.

How to migrate from NPM, Yarn, or PNPM to Bun

Since Bun 1.1, bun install can auto-migrate from existing lockfiles. But the cleanest approach is still to remove the old lockfile first, then let Bun generate a fresh bun.lock.

rm package-lock.json
bun install

rm yarn.lock
bun install

rm pnpm-lock.yaml
bun install

Verify: ls bun.lock should exist, ls node_modules should show installed packages, and bun run build (or your project’s build command) should succeed.

If you run into issues with native addons, check bun pm untrusted. Bun blocks lifecycle scripts (postinstall, etc.) by default since Bun 1.1. See the troubleshooting section below for how to trust packages.

For a full Astro migration walkthrough, see migrate Astro to Bun on CloudFlare.

Bun command reference: essential commands & npm equivalents

Core commands

Checking for outdated packages

bun outdated
# Shows all outdated packages with current and latest versions

bun outdated --filter '@myorg/*'
# Filter to specific scope

Updating packages

bun update <package>            # Update within semver range
bun update <package> --latest   # Update to latest, ignoring semver
bun update                      # Update all deps within semver range
bun update --interactive        # Pick which deps to update interactively

For a deeper dive into updating packages with Bun, see how to update Node packages with Bun and how to update all Node.js dependencies.

Security and trust

bun pm untrusted          # List packages with blocked lifecycle scripts
bun pm trust <package>    # Trust a specific package
bun pm trust --all        # Trust all packages (use with caution)

Real-world benchmark: Bun install speed test

I ran this test on the bitdoze.com Astro blog. The project has a typical mix of dependencies. Here are the raw numbers:

NPM:

➜  bitdoze-astro-bkw git:(main) time npm install

npm install  13.22s user 3.82s system 23% cpu 1:13.89 total

npm run build  55.96s user 3.41s system 126% cpu 46.776 total

Bun:

➜  bitdoze-astro-bkw git:(main) time bun install

bun install  10.83s user 2.14s system 121% cpu 10.694 total

bun run build  55.30s user 3.34s system 126% cpu 46.181 total

Results: Bun install took ~11 seconds. npm install took 73 seconds. That’s 7x faster for this project. The build process was identical. The same Astro build runs at the same speed regardless of which package manager installed the dependencies.

This was tested in February 2024 and re-verified in July 2026. Bun 1.2+ is roughly 30% faster than the version originally tested, so the gap has likely widened for new installs. For a look at how Astro 7 improved build speeds, see Astro 7 benchmark: build times cut in half. You can also optimize Astro build speeds further with SSG-specific tweaks.

Your results will vary based on project size, dependency count, hardware, and network conditions.

Bun in Docker & CI/CD: production best practices

Dockerfile example

Bun provides official Docker images. Use oven/bun:alpine for the build stage (smaller, musl-based) and oven/bun:distroless for the runtime (minimal attack surface):

FROM oven/bun:alpine AS builder
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

FROM oven/bun:distroless AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["bun", "run", "start"]

To skip devDependencies in production:

bun install --frozen-lockfile --production

CI/CD with GitHub Actions

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bun test

Common failure: if --frozen-lockfile fails, it means your bun.lock doesn’t match package.json. Run bun install locally, commit the lockfile, and push.

For more Docker commands and patterns, see top Docker commands you must know.

Bun usage examples

Add and remove packages

# Add packages
bun add tailwindcss autoprefixer postcss

# Add a dev dependency
bun add prettier --dev

# Remove a package
bun remove tailwindcss

Run scripts

bun run dev      # Run the "dev" script from package.json
bun run build    # Run the "build" script
bun run test     # Run the "test" script

For monorepos with workspaces, run scripts in specific packages:

bun run --filter @myorg/web build

Check and update dependencies

# See what's outdated
bun outdated

# Update interactively (Bun 1.3+)
bun update --interactive

# Update a specific package to latest
bun update tailwindcss --latest

Audit for vulnerabilities

bun audit
# Scans dependencies for known security vulnerabilities

Troubleshooting common Bun issues

curl -fsSL https://bun.sh/install | bash -s -- --baseline

powershell -c "irm bun.sh/install.ps1 -- --baseline | iex"

# bash (~/.bashrc) or zsh (~/.zshrc)
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

set --export BUN_INSTALL "$HOME/.bun"
set --export PATH "$BUN_INSTALL/bin" $PATH

bun pm untrusted          # See which packages are blocked
bun pm trust <package>    # Trust a specific package
bun pm trust --all        # Trust all (use with caution)

{
  "trustedDependencies": ["package-name"]
}

uname -r

[install.scopes]
"@myorg" = { url = "https://registry.myorg.com", token = "npm_..." }

//registry.myorg.com/:_authToken=npm_...
@myorg:registry=https://registry.myorg.com

rm -rf node_modules bun.lock
npm install

Frequently asked questions

Conclusion

Bun as a package manager is production-ready and significantly faster than npm, yarn, or pnpm for install times. The text-based bun.lock, full Windows support, and Anthropic backing have addressed the main concerns from when this article was first published.

My recommendation: try Bun as a package manager on your next project. Remove the old lockfile, run bun install, and see how it feels. You can always roll back if something breaks.

The runtime side (replacing Node.js) is a separate decision with more nuance. But for bun install vs npm install? There’s no contest.