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

1. ~/.npmrc (or $XDG_CONFIG_HOME/.npmrc)
2. ./.npmrc
3. bunfig.toml (global, then project)
4. BUN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY and BUN_CONFIG_TOKEN / NPM_CONFIG_TOKEN environment variables
5. 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.

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:

registry=http://localhost:4873/

The equivalent bunfig.toml option is install.registry:

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

Set the registry for a specific scope#

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

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

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

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

Configure options for a specific registry#

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

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

[install.scopes]
# unlike _password in .npmrc, password is not base64 encoded; Bun encodes it for you
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:

link-workspace-packages=true

The equivalent bunfig.toml option is install.linkWorkspacePackages:

[install]
linkWorkspacePackages = true

save-exact: Save exact versions#

Always saves exact versions without the ^ prefix:

save-exact=true

The equivalent bunfig.toml option is install.exact:

[install]
exact = true

ignore-scripts: Skip lifecycle scripts#

Prevents running lifecycle scripts during installation:

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:

dry-run=true

The equivalent bunfig.toml option is install.dryRun:

[install]
dryRun = true

cache: Configure cache directory#

Set the cache directory path, or disable caching:

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

# or disable caching
cache=false

The equivalent bunfig.toml option is install.cache:

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

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

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

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

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

# 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