Skip to main content
bun install reads your package.json and installs all dependencies into node_modules. It is a drop-in replacement for npm install, yarn install, and pnpm install and works in any existing Node.js project. 
bun install
Running bun install will:
  • Install all dependencies, devDependencies, optionalDependencies, and peerDependencies
  • Run your project’s {pre|post}install and {pre|post}prepare scripts
  • Write a bun.lock lockfile to the project root
25x faster — Bun’s package manager benchmarks up to 25x faster than npm install on a warm cache, thanks to its global cache and efficient hard-linking strategy.

​
Flags

​
--production

Install only dependencies, skipping devDependencies and optionalDependencies. 
bun install --production

​
--frozen-lockfile

Install exact versions from bun.lock. Exits with an error if package.json disagrees with the lockfile. The lockfile is never updated. 
bun install --frozen-lockfile
Use this flag in CI to enforce reproducible builds. See also: bun ci, which is equivalent. 
bun ci

​
--no-save

Install packages without creating or updating the lockfile. 
bun install --no-save

​
--dry-run

Resolve packages and show what would be installed, without writing anything to disk. 
bun install --dry-run

​
--omit

Exclude specific dependency types from installation. 
# Exclude devDependencies
bun install --omit dev

# Exclude multiple types
bun install --omit=dev --omit=peer --omit=optional

​
--lockfile-only

Resolve and write bun.lock without installing packages into node_modules. 
bun install --lockfile-only

​
Global cache

Bun stores all downloaded packages in a global cache at ~/.bun/install/cache. When a package is already cached, Bun reuses it instead of downloading again. Packages are linked from the cache into node_modules using the fastest available system call:
  • Linux and Windows: hardlinks (files occupy disk space only once)
  • macOS: clonefile (copy-on-write, no extra disk usage)
This means multiple projects sharing the same dependency version use virtually no additional disk space. To clear the cache: 
bun pm cache rm
To use a custom cache location, set BUN_INSTALL_CACHE_DIR or configure bunfig.toml: 
[install.cache]
dir = "~/.bun/install/cache"

​
Non-npm dependencies

Bun supports installing dependencies from Git, GitHub, and remote tarballs directly in package.json. 
{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz"
  }
}

​
Installation strategies

Bun supports two strategies for how packages are placed in node_modules.

​
Hoisted

The traditional npm/Yarn approach. All packages are flattened into the root node_modules directory. 
bun install --linker hoisted

​
Isolated

A pnpm-like approach that prevents phantom dependencies. A central store is created at node_modules/.bun/, and packages link only to their declared dependencies. 
bun install --linker isolated
The default strategy depends on whether you’re starting a new project or migrating an existing one. New monorepos default to isolated; single-package projects and existing projects (pre-v1.3.2) default to hoisted.

​
.npmrc compatibility

Bun reads .npmrc files for registry and scope configuration, making it compatible with existing npm setups without any changes. See Registries & Scopes for details.

​
bunfig.toml configuration

All bun install behavior can be configured in bunfig.toml. 
[install]

# whether to install optional dependencies
optional = true

# whether to install devDependencies
dev = true

# whether to install peerDependencies
peer = true

# equivalent to --production flag
production = false

# equivalent to --frozen-lockfile flag
frozenLockfile = false

# equivalent to --dry-run flag
dryRun = false

# save text-based lockfile (bun.lock) instead of binary (bun.lockb)
saveTextLockfile = false

# installation strategy: "hoisted" or "isolated"
linker = "hoisted"

# number of concurrent lifecycle scripts
concurrentScripts = 16

​
CI/CD

Use the official oven-sh/setup-bun GitHub Action to install Bun in CI: 
name: CI
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun ci
      - run: bun run build
bun ci is equivalent to bun install --frozen-lockfile. It requires bun.lock to be committed to version control.

​
pnpm migration

When a pnpm-lock.yaml is present and no bun.lock exists, Bun automatically migrates the lockfile to bun.lock format during installation. The original pnpm-lock.yaml is left untouched. 
bun install
Bun also migrates workspace configuration from pnpm-workspace.yaml into the root package.json automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us