Bun Package Manager

Bun Package Manager

Bun's package manager is a dramatically faster replacement for npm, yarn, and pnpm. Up to 25x faster than npm install.

Quick Start

# Install all dependenciesbun install
# Add packagesbun add react react-dombun add -D typescript @types/react
# Remove packagesbun remove lodash
# Update packagesbun update
# Run package binariesbunx create-next-app

Core Commands

Installation Flags

# Production mode (no devDependencies)bun install --production
# Frozen lockfile (CI/CD)bun install --frozen-lockfilebun ci  # shorthand
# Dry runbun install --dry-run
# Verbose/Silentbun install --verbosebun install --silent
# Force reinstallbun install --force
# Global packagesbun install -g cowsay

Lockfile

Bun uses bun.lock (text-based since v1.2):

# Generate text lockfilebun install --save-text-lockfile
# Upgrade from binary bun.lockbbun install --save-text-lockfile --frozen-lockfile --lockfile-onlyrm bun.lockb

Workspaces (Monorepos)

{  "name": "my-monorepo",  "workspaces": ["packages/*", "apps/*"]}

Run commands across workspaces:

# Run in matching packagesbun run --filter 'pkg-*' build
# Run in all workspacesbun run --filter '*' test
# Install for specific packagesbun install --filter 'pkg-a'

Lifecycle Scripts

Bun does not run lifecycle scripts from dependencies by default (security). Whitelist trusted packages:

{  "trustedDependencies": ["my-trusted-package"]}

# Skip all lifecycle scriptsbun install --ignore-scripts
# Concurrent scriptsbun install --concurrent-scripts 5

Overrides & Resolutions

Force specific versions for nested dependencies:

{  "overrides": {    "lodash": "4.17.21"  }}

Yarn-style resolutions also supported:

{  "resolutions": {    "lodash": "4.17.21"  }}

Non-npm Dependencies

{  "dependencies": {    "dayjs": "git+https://github.com/iamkun/dayjs.git",    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",    "zod": "github:colinhacks/zod",    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",    "bun-types": "npm:@types/bun"  }}

Installation Strategies

Bun 1.3+ default flip: Starting in Bun 1.3, isolated is the default for workspaces (packages can no longer reach undeclared deps through the hoisted root node_modules). hoisted is now the legacy opt-out — only use it when a workspace package depends on a transitive dep that it doesn't declare.

Hoisted (legacy opt-out; still the default for single non-workspace packages)

Traditional flat node_modules:

bun install --linker hoisted

Isolated (default for workspaces in Bun 1.3+)

pnpm-like strict isolation:

bun install --linker isolated

Isolated prevents "phantom dependencies" - packages can only access declared dependencies. To make this explicit or restore it after an opt-out, set it in bunfig.toml:

[install]linker = "isolated"   # default for workspaces in Bun 1.3+# linker = "hoisted"  # legacy opt-out

CI/CD

# GitHub Actions- uses: oven-sh/setup-bun@v2- run: bun ci  # frozen lockfile

Platform-Specific

# Install for different platformbun install --cpu=x64 --os=linux

Secure Installation

When installing packages, follow supply chain security best practices:

• Block post-install scripts — Bun disables them by default; allow specific packages via trustedDependencies in package.json
• Cooldown period — Configure minimumReleaseAge in bunfig.toml to wait 7 days for new versions
• Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages before they reach your project

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

Common Errors

Migration from Other Package Managers

From pnpm

Bun automatically migrates pnpm-lock.yaml:

bun install  # Auto-converts to bun.lock

Workspace config moves to package.json:

{  "workspaces": {    "packages": ["apps/*", "packages/*"],    "catalog": {      "react": "^18.0.0"    }  }}

From npm/Yarn

Simply run bun install - Bun reads package-lock.json and yarn.lock.

When to Load References

Load references/cli-commands.md when:

• Need complete CLI flag reference
• Working with advanced options

Load references/workspaces.md when:

• Setting up monorepos
• Configuring workspace filters

Load references/migration.md when:

• Migrating from npm/yarn/pnpm
• Converting lockfiles