Skip to main content
Bun supports loading configuration options from .npmrc files, allowing you to reuse existing registry/scope configurations.
We recommend migrating your .npmrc file to Bun’s bunfig.toml format, as it provides more flexible options and can let you configure Bun-specific options.

​
Supported options

​
Set the default registry

The default registry is used to resolve packages, its default value is npm’s official registry (https://registry.npmjs.org/). To change it, you can 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 allows you to set 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> allows you to set 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}
The following options are supported:
  • _authToken
  • username
  • _password (base64 encoded password)
  • _auth (base64 encoded username:password, e.g. 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" }
Controls how workspace packages are installed when 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 would be installed without actually installing:
.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 are installed:
.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 packages are installed in node_modules. Bun supports two different configuration options for compatibility with different package managers. npm’s install-strategy:
.npmrc
# flat node_modules structure (default)
install-strategy=hoisted

# symlinked structure
install-strategy=linked
pnpm/yarn’s node-linker: The node-linker option controls the installation mode. Bun supports values from both pnpm and yarn:
ValueDescriptionAccepted by
isolatedSymlinked structure with isolated dependenciespnpm
hoistedFlat node_modules structurepnpm
pnpmSymlinked structure (same as isolated)yarn
node-modulesFlat 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 are hoisted 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=*