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

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

Hoisted (default for single packages)

Traditional flat node_modules:

bun install --linker hoisted

Isolated (default for workspaces)

pnpm-like strict isolation:

bun install --linker isolated

Isolated prevents "phantom dependencies" - packages can only access declared dependencies.

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

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

Bun Package Manager CLI Reference

bun install

bun install [flags]

General Configuration

Dependency Scope

Dependency Type

Lockfile

Network

Installation Control

Cache

Output

Security

Performance

Lifecycle

bun add

bun add <packages> [flags]

All bun install flags plus:

bun add react                  # Latest
bun add react@19               # Major version
bun add react@19.1.1           # Exact version
bun add react@latest           # Latest tag
bun add react@next             # Next tag
bun add -D typescript          # Dev dependency
bun add -O fsevents            # Optional dependency

bun remove

bun remove <packages>

Removes from package.json and node_modules.

bun update

bun update [packages]

Updates packages to latest allowed by semver.

bun update           # Update all
bun update react     # Update specific
bun update --latest  # Ignore semver ranges

bunx

bunx <package> [args]

Run package binary (like npx):

bunx create-next-app my-app
bunx tsc --version
bunx prisma generate

bun pm

Package manager utilities:

bun pm cache rm           # Clear cache
bun pm cache              # Show cache path
bun pm bin                # Show bin directory
bun pm bin -g             # Global bin directory
bun pm ls                 # List installed packages
bun pm hash               # Show lockfile hash
bun pm hash-string        # Deterministic hash
bun pm hash-print         # Print hash details
bun pm migrate            # Migrate from other PMs

bun link

# In package directory
bun link

# In consuming project
bun link <package-name>

# Unlink
bun unlink
bun unlink <package-name>

bun publish

bun publish [flags]

Publish to npm registry.

bun outdated

bun outdated           # Show outdated packages
bun outdated --filter  # Filter workspaces

bun why

bun why <package>      # Show why installed

bun audit

bun audit              # Check for vulnerabilities

bun patch

bun patch <package>    # Create patch
bun patch --commit     # Apply patch