> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# bun install

> Install all dependencies from package.json with Bun's fast package manager — up to 25x faster than npm.

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

```bash theme={null}
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

<Note>
  **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.
</Note>

## Flags

### `--production`

Install only `dependencies`, skipping `devDependencies` and `optionalDependencies`.

```bash theme={null}
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.

```bash theme={null}
bun install --frozen-lockfile
```

Use this flag in CI to enforce reproducible builds. See also: `bun ci`, which is equivalent.

```bash theme={null}
bun ci
```

### `--no-save`

Install packages without creating or updating the lockfile.

```bash theme={null}
bun install --no-save
```

### `--dry-run`

Resolve packages and show what would be installed, without writing anything to disk.

```bash theme={null}
bun install --dry-run
```

### `--omit`

Exclude specific dependency types from installation.

```bash theme={null}
# 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`.

```bash theme={null}
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:

```bash theme={null}
bun pm cache rm
```

To use a custom cache location, set `BUN_INSTALL_CACHE_DIR` or configure `bunfig.toml`:

```toml theme={null}
[install.cache]
dir = "~/.bun/install/cache"
```

## Non-npm dependencies

Bun supports installing dependencies from Git, GitHub, and remote tarballs directly in `package.json`.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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](/pm/registries) for details.

## bunfig.toml configuration

All `bun install` behavior can be configured in `bunfig.toml`.

```toml theme={null}
[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`](https://github.com/oven-sh/setup-bun) GitHub Action to install Bun in CI:

```yaml theme={null}
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.

```bash theme={null}
bun install
```

Bun also migrates workspace configuration from `pnpm-workspace.yaml` into the root `package.json` automatically.