> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

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

```toml theme={null}
[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:password@registry.npmjs.org"
```

Or with an environment variable:

```bash theme={null}
BUN_CONFIG_REGISTRY=https://registry.npmjs.org bun install
```

## Scoped registries

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

```toml theme={null}
[install.scopes]
# plain URL with credentials in the URL
"@myorg1" = "https://username:password@registry.myorg.com/"

# 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/" }
```

<Tip>
  Use environment variable references like `"$NPM_TOKEN"` to avoid committing credentials to source control.
</Tip>

## Private registries

### GitHub Packages

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

### Verdaccio (self-hosted)

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

### Azure Artifacts

```toml theme={null}
[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

```ini theme={null}
registry=http://localhost:4873/
```

### Set a scoped registry

```ini theme={null}
@myorg:registry=https://npm.pkg.github.com/
```

### Authentication

```ini theme={null}
# 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`.

<Note>
  We recommend migrating `.npmrc` to `bunfig.toml` for access to Bun-specific configuration options.
</Note>

## Logging in

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

```bash theme={null}
bunx npm login --registry https://npm.pkg.github.com
```

After logging in, check the current user:

```bash theme={null}
bun pm whoami
```