Skip to main content
Bun loads configuration options from .npmrc files, so you can reuse your existing registry and scope configuration.
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}
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:
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 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 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 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 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:
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=*