Registries & Scopes

Configure custom registries, scoped packages, and authentication tokens for private npm registries.

The default registry is https://registry.npmjs.org. You can configure a different default registry or use per-scope registries for private packages — in both bunfig.toml and .npmrc.

Default registry

Set a custom default registry in bunfig.toml:

[install]
# registry as a plain URL
registry = "https://registry.npmjs.org"

# registry with an auth token
registry = { url = "https://registry.npmjs.org", token = "123456" }

# registry with username and password
registry = "https://username:[e-mail]"

Or with an environment variable:

BUN_CONFIG_REGISTRY=https://registry.npmjs.org bun install

Scoped registries

Route packages under a specific @scope to a different registry:

[install.scopes]
# plain URL with credentials in the URL
"@myorg1" = "https://username:[e-mail]/"

# with username/password (can reference environment variables)
"@myorg2" = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" }

# with an auth token
"@myorg3" = { token = "$NPM_TOKEN", url = "https://registry.myorg.com/" }

Use environment variable references like "$NPM_TOKEN" to avoid committing credentials to source control.

Private registries

GitHub Packages

[install.scopes]
"@myorg" = { token = "$GITHUB_TOKEN", url = "https://npm.pkg.github.com/" }

Verdaccio (self-hosted)

[install]
registry = { url = "http://localhost:4873/", token = "$NPM_TOKEN" }

Azure Artifacts

[install.scopes]
"@myorg" = { token = "$AZURE_ARTIFACTS_TOKEN", url = "https://pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/" }

.npmrc compatibility

Bun also reads .npmrc files, so existing npm configurations work without changes.

Set the default registry

registry=http://localhost:4873/

Set a scoped registry

@myorg:registry=https://npm.pkg.github.com/

Authentication

# auth token for a registry
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

# username and password (password is base64 encoded)
//registry.myorg.com/:username=myusername
//registry.myorg.com/:_password=${NPM_PASSWORD}

# combined base64 username:password
//registry.myorg.com/:_auth=${NPM_AUTH}

Supported authentication fields: _authToken, username, _password, _auth, email.

We recommend migrating .npmrc to bunfig.toml for access to Bun-specific configuration options.

Logging in

To authenticate with a registry interactively, use bunx npm login:

bunx npm login --registry https://npm.pkg.github.com

After logging in, check the current user:

bun pm whoami