.npmrc support

Bun loads configuration options from .npmrc files, so you can reuse your existing registry and scope configuration. Configuration is loaded in this order, with later sources overriding earlier ones:

~/.npmrc (or $XDG_CONFIG_HOME/.npmrc)
./.npmrc
bunfig.toml (global, then project)
BUN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY and BUN_CONFIG_TOKEN / NPM_CONFIG_TOKEN environment variables
Command-line flags such as --registry

Bun matches credentials in .npmrc (//<registry>/:_authToken, etc.) to registries by host and path, even if you set the registry URL itself in bunfig.toml. Values may reference environment variables. Bun replaces ${NAME} with the variable’s value, or leaves it as-is if the variable is unset. ${NAME?} becomes an empty string if unset.

We recommend migrating your .npmrc file to Bun’s bunfig.toml format, which supports more options, including Bun-specific ones.

Supported options

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:

.npmrc

registry=http://localhost:4873/

The equivalent bunfig.toml option is install.registry:

bunfig.toml

install.registry = "http://localhost:4873/"

Set the registry for a specific scope

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

.npmrc

@myorg:registry=http://localhost:4873/

The equivalent bunfig.toml option is to add a key in install.scopes:

bunfig.toml

[install.scopes]
myorg = "http://localhost:4873/"

Configure options for a specific registry

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

.npmrc

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

Bun supports the following options:

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

bunfig.toml

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

`link-workspace-packages`: Control workspace package installation

Controls how Bun installs workspace packages when they are available locally:

.npmrc

link-workspace-packages=true

The equivalent bunfig.toml option is install.linkWorkspacePackages:

bunfig.toml

[install]
linkWorkspacePackages = true

`save-exact`: Save exact versions

Always saves exact versions without the ^ prefix:

.npmrc

save-exact=true

The equivalent bunfig.toml option is install.exact:

bunfig.toml

[install]
exact = true

`ignore-scripts`: Skip lifecycle scripts

Prevents running lifecycle scripts during installation:

.npmrc

ignore-scripts=true

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

`dry-run`: Preview changes without installing

Shows what Bun would install without installing anything:

.npmrc

dry-run=true

The equivalent bunfig.toml option is install.dryRun:

bunfig.toml

[install]
dryRun = true

`cache`: Configure cache directory

Set the cache directory path, or disable caching:

.npmrc

# set a custom cache directory
cache=/path/to/cache

# or disable caching
cache=false

The equivalent bunfig.toml option is install.cache:

bunfig.toml

[install.cache]
# set a custom cache directory
dir = "/path/to/cache"

# or disable caching
disable = true

`ca` and `cafile`: Configure CA certificates

Configure custom CA certificates for registry connections:

.npmrc

# 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

Control which dependency types Bun installs:

.npmrc

# 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

Control how Bun lays out packages 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 for how the hoisted and isolated layouts differ. npm’s install-strategy:

.npmrc

# 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

.npmrc

# 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

Control which packages Bun hoists to the root node_modules:

.npmrc

# 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=*

# isolated linker only: disable the node_modules/.bun/node_modules fallback,
# so store packages only resolve declared deps (plus the root node_modules).
# Hoisted installs ignore this setting.
hoist=false

Core Commands

Publishing & Analysis

Workspace Management

Advanced Configuration

.npmrc support

Supported options

Set the default registry

Set the registry for a specific scope

Configure options for a specific registry

`link-workspace-packages`: Control workspace package installation

`save-exact`: Save exact versions

`ignore-scripts`: Skip lifecycle scripts

`dry-run`: Preview changes without installing

`cache`: Configure cache directory

`ca` and `cafile`: Configure CA certificates

`omit` and `include`: Control dependency types

`install-strategy` and `node-linker`: Installation strategy

`public-hoist-pattern` and `hoist-pattern`: Control hoisting

​Supported options

​Set the default registry

​Set the registry for a specific scope

​Configure options for a specific registry

​link-workspace-packages: Control workspace package installation

​save-exact: Save exact versions

​ignore-scripts: Skip lifecycle scripts

​dry-run: Preview changes without installing

​cache: Configure cache directory

​ca and cafile: Configure CA certificates

​omit and include: Control dependency types

​install-strategy and node-linker: Installation strategy

​public-hoist-pattern and hoist-pattern: Control hoisting

Supported options

Set the default registry

Set the registry for a specific scope

Configure options for a specific registry

`link-workspace-packages`: Control workspace package installation

`save-exact`: Save exact versions

`ignore-scripts`: Skip lifecycle scripts

`dry-run`: Preview changes without installing

`cache`: Configure cache directory

`ca` and `cafile`: Configure CA certificates

`omit` and `include`: Control dependency types

`install-strategy` and `node-linker`: Installation strategy

`public-hoist-pattern` and `hoist-pattern`: Control hoisting