# .npmrc support (/docs/pm/npmrc)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1747 · updated: 2026-07-28 -->
Related: [bunx](/docs/pm/bunx.md), [Workspaces](/docs/pm/workspaces.md), [Catalogs](/docs/pm/catalogs.md), [bun --filter](/docs/pm/filter.md), [Global cache](/docs/pm/global-cache.md), [Global virtual store](/docs/pm/global-store.md)

Bun loads configuration options from [`.npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc) files, so you can reuse your existing registry and scope configuration.

<Note>
  We recommend migrating your `.npmrc` file to Bun's [`bunfig.toml`](/runtime/bunfig) format, which supports more
  options, including Bun-specific ones.
</Note>

***

## Supported options [#supported-options]

### Set the default registry [#set-the-default-registry]

Bun resolves packages from the default registry, which is `npm`'s official registry (`https://registry.npmjs.org/`).

To change it, set the `registry` option in `.npmrc`:

```ini .npmrc icon="npm"
registry=http://localhost:4873/
```

The equivalent `bunfig.toml` option is [`install.registry`](/runtime/bunfig#install-registry):

```toml bunfig.toml icon="settings"
install.registry = "http://localhost:4873/"
```

### Set the registry for a specific scope [#set-the-registry-for-a-specific-scope]

`@<scope>:registry` sets the registry for a specific scope:

```ini .npmrc icon="npm"
@myorg:registry=http://localhost:4873/
```

The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):

```toml bunfig.toml icon="settings"
[install.scopes]
myorg = "http://localhost:4873/"
```

### Configure options for a specific registry [#configure-options-for-a-specific-registry]

`//<registry_url>/:<key>=<value>` sets options for a specific registry:

```ini .npmrc icon="npm"
# set an auth token for the registry
# ${...} is a placeholder for environment variables
//http://localhost:4873/:_authToken=${NPM_TOKEN}


# or you could set a username and password
# note that the password is base64 encoded
//http://localhost:4873/:username=myusername

//http://localhost:4873/:_password=${NPM_PASSWORD}

# or use _auth, which is your username and password
# combined into a single string, which is then base 64 encoded
//http://localhost:4873/:_auth=${NPM_AUTH}
```

The following options are supported:

* `_authToken`
* `username`
* `_password` (base64 encoded password)
* `_auth` (base64 encoded username:password, for example `btoa(username + ":" + password)`)
* `email`

The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):

```toml bunfig.toml icon="settings"
[install.scopes]
myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }
```

### `link-workspace-packages`: Control workspace package installation [#link-workspace-packages-control-workspace-package-installation]

Controls how workspace packages are installed when available locally:

```ini .npmrc icon="npm"
link-workspace-packages=true
```

The equivalent `bunfig.toml` option is [`install.linkWorkspacePackages`](/runtime/bunfig#install-linkworkspacepackages):

```toml bunfig.toml icon="settings"
[install]
linkWorkspacePackages = true
```

### `save-exact`: Save exact versions [#save-exact-save-exact-versions]

Always saves exact versions without the `^` prefix:

```ini .npmrc icon="npm"
save-exact=true
```

The equivalent `bunfig.toml` option is [`install.exact`](/runtime/bunfig#install-exact):

```toml bunfig.toml icon="settings"
[install]
exact = true
```

### `ignore-scripts`: Skip lifecycle scripts [#ignore-scripts-skip-lifecycle-scripts]

Prevents running lifecycle scripts during installation:

```ini .npmrc icon="npm"
ignore-scripts=true
```

This is equivalent to using the `--ignore-scripts` flag with `bun install`.

### `dry-run`: Preview changes without installing [#dry-run-preview-changes-without-installing]

Shows what would be installed without installing anything:

```ini .npmrc icon="npm"
dry-run=true
```

The equivalent `bunfig.toml` option is [`install.dryRun`](/runtime/bunfig#install-dryrun):

```toml bunfig.toml icon="settings"
[install]
dryRun = true
```

### `cache`: Configure cache directory [#cache-configure-cache-directory]

Set the cache directory path, or disable caching:

```ini .npmrc icon="npm"
# set a custom cache directory
cache=/path/to/cache

# or disable caching
cache=false
```

The equivalent `bunfig.toml` option is [`install.cache`](/runtime/bunfig#install-cache):

```toml bunfig.toml icon="settings"
[install.cache]
# set a custom cache directory
dir = "/path/to/cache"

# or disable caching
disable = true
```

### `ca` and `cafile`: Configure CA certificates [#ca-and-cafile-configure-ca-certificates]

Configure custom CA certificates for registry connections:

```ini .npmrc icon="npm"
# single CA certificate
ca="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# multiple CA certificates
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# or specify a path to a CA file
cafile=/path/to/ca-bundle.crt
```

### `omit` and `include`: Control dependency types [#omit-and-include-control-dependency-types]

Control which dependency types are installed:

```ini .npmrc icon="npm"
# omit dev dependencies
omit=dev

# omit multiple types
omit[]=dev
omit[]=optional

# include specific types (overrides omit)
include=dev
```

Valid values: `dev`, `peer`, `optional`

### `install-strategy` and `node-linker`: Installation strategy [#install-strategy-and-node-linker-installation-strategy]

Control how packages are laid out in `node_modules`. For compatibility with other package managers, Bun accepts both npm's `install-strategy` and pnpm/yarn's `node-linker`. See [isolated installs](/pm/isolated-installs) for how the hoisted and isolated layouts differ.

**npm's `install-strategy`:**

```ini .npmrc icon="npm"
# flat node_modules structure (default)
install-strategy=hoisted

# symlinked structure
install-strategy=linked
```

**pnpm/yarn's `node-linker`:**

`node-linker` controls the installation mode. Bun accepts values from both pnpm and yarn:

| Value          | Description                                      | Accepted by |
| -------------- | ------------------------------------------------ | ----------- |
| `isolated`     | Symlinked structure with isolated dependencies   | pnpm        |
| `hoisted`      | Flat node\_modules structure                     | pnpm        |
| `pnpm`         | Symlinked structure (same as `isolated`)         | yarn        |
| `node-modules` | Flat node\_modules structure (same as `hoisted`) | yarn        |

```ini .npmrc icon="npm"
# symlinked/isolated mode
node-linker=isolated
node-linker=pnpm

# flat/hoisted mode
node-linker=hoisted
node-linker=node-modules
```

### `public-hoist-pattern` and `hoist-pattern`: Control hoisting [#public-hoist-pattern-and-hoist-pattern-control-hoisting]

Control which packages are hoisted to the root `node_modules`:

```ini .npmrc icon="npm"
# packages matching this pattern will be hoisted to the root
public-hoist-pattern=*eslint*

# multiple patterns
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# control general hoisting behavior
hoist-pattern=*
```