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 dependencies
bun install

# Add packages
bun add react react-dom
bun add -D typescript @types/react

# Remove packages
bun remove lodash

# Update packages
bun update

# Run package binaries
bunx create-next-app

Core Commands

Command	Description
bun install	Install all dependencies
bun add <pkg>	Add dependency
bun add -D <pkg>	Add dev dependency
bun add -O <pkg>	Add optional dependency
bun add --peer <pkg>	Add peer dependency
bun remove <pkg>	Remove dependency
bun update [pkg]	Update dependencies
bunx <pkg>	Run package binary
bun pm cache rm	Clear cache

Installation Flags

# Production mode (no devDependencies)
bun install --production

# Frozen lockfile (CI/CD)
bun install --frozen-lockfile
bun ci  # shorthand

# Dry run
bun install --dry-run

# Verbose/Silent
bun install --verbose
bun install --silent

# Force reinstall
bun install --force

# Global packages
bun install -g cowsay

Lockfile

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

# Generate text lockfile
bun install --save-text-lockfile

# Upgrade from binary bun.lockb
bun install --save-text-lockfile --frozen-lockfile --lockfile-only
rm bun.lockb

Workspaces (Monorepos)

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

Run commands across workspaces:

# Run in matching packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

# Install for specific packages
bun 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 scripts
bun install --ignore-scripts

# Concurrent scripts
bun 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 platform
bun 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

Error	Cause	Fix
Cannot find module	Missing dependency	Run bun install
Lockfile mismatch	package.json changed	Run bun install
Peer dependency	Missing peer	bun add the peer
Lifecycle script failed	Untrusted package	Add to trustedDependencies

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