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
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
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