Version: Next

Authentication Settings

The settings on this page contain sensitive credentials and are stored in INI-formatted files. Do not commit these files to your repository.

For non-sensitive settings (proxy, SSL, registries, etc.), see Settings (pnpm-workspace.yaml).

Auth file locations

pnpm reads authentication settings from the following files, in order of priority (highest first):

<workspace root>/.npmrc — project-level auth. This file should be listed in .gitignore.
<pnpm config>/auth.ini — the primary user-level auth file. pnpm login writes tokens here.
~/.npmrc — read as a fallback for easier migration from npm. Use the npmrcAuthFile setting to point to a different file.

The <pnpm config> directory is:

If the $XDG_CONFIG_HOME env variable is set: $XDG_CONFIG_HOME/pnpm/
On Windows: ~/AppData/Local/pnpm/config/
On macOS: ~/Library/Preferences/pnpm/
On Linux: ~/.config/pnpm/

Environment variables in auth settings

Values in the user-level auth files (<pnpm config>/auth.ini and the user .npmrc) may reference environment variables using the ${NAME} syntax:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Since v11.5.3, environment variables are not expanded in the project-level .npmrc at the workspace root for the following settings:

registry and proxy URLs (registry, @scope:registry, proxy settings);
URL-scoped keys (keys starting with //);
credential values (_authToken, _auth, _password, username, tokenHelper, cert, key).

A setting that contains a ${...} placeholder in any of these positions is ignored, and pnpm prints a warning. The project .npmrc is checked out together with the repository, so expanding environment variables there would allow a malicious repository to exfiltrate secrets from your environment (such as CI tokens) to an attacker-controlled registry during installation (GHSA-3qhv-2rgh-x77r).

If your project relied on a committed .npmrc containing a line like //registry.npmjs.org/:_authToken=${NPM_TOKEN}, move the token to a trusted location instead:

Write the token to the user-level auth file before installing (for example, in a CI step):
```
pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
```
pnpm config set writes to the global location by default (<pnpm config>/auth.ini for auth settings), not to the project .npmrc, so the token never ends up in the repository.
Set the credential through an environment variable, with no .npmrc file at all (since v11.6). pnpm reads URL-scoped registry settings from pnpm_config_//… environment variables:
```
env "pnpm_config_//registry.npmjs.org/:_authToken=$NPM_TOKEN" pnpm install
```
The variable name contains /, :, and ., which export and the NAME=value shell assignment syntax reject as invalid identifiers. Use the env utility (as shown above) to pass it to a single command, or set it through a tool that accepts arbitrary variable names (for example, your CI provider's environment settings or Node's process.env).

This is the most direct, file-free replacement for a committed //registry.npmjs.org/:_authToken=${NPM_TOKEN} line. Because the registry the credential applies to is encoded in the (trusted) variable name, a malicious repository cannot redirect it to another host. Such an environment value overrides the project .npmrc but is itself overridden by a command-line option. The tokenHelper setting is intentionally not read from environment variables.
Or keep the ${NPM_TOKEN} placeholder line, but put it in the user-level ~/.npmrc (or the file referenced by npmrcAuthFile) instead of the repository.
In GitHub Actions, actions/setup-node with the registry-url input writes the auth setting to a user-level .npmrc (referenced by the NPM_CONFIG_USERCONFIG environment variable, which pnpm honors), so authentication via the NODE_AUTH_TOKEN environment variable continues to work.
If you cannot easily modify each CI pipeline, you may declare the project .npmrc trusted by setting a single environment variable in the CI environment (for example, at the organization or workspace level):
```
PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc
```
This is the env form of the npmrcAuthFile setting: it makes pnpm read the project's .npmrc as the user-level auth file (a relative path is resolved against the working directory), so environment variables in it are expanded as before. Because the trust declaration comes from the environment — not from the repository — a malicious repository cannot set it for you. The npm-style NPM_CONFIG_USERCONFIG variable is also honored as a fallback.

危険
Only use this in environments that exclusively build trusted repositories. It disables this protection entirely for the checked-out repository, including the restriction that tokenHelper may only be set in user-level config.

The same rule applies to registry and proxy URLs in a project .npmrc (registry, @scope:registry, proxy, https-proxy, http-proxy). If you used an environment variable to build a registry URL, move the setting to a trusted source — your user-level ~/.npmrc, or pnpm config set "<key>" <value>. If the URL is not secret, you can also write the resolved value directly in the project .npmrc, since only ${...} placeholders are ignored. For registry settings in pnpm-workspace.yaml, see Settings.

Authentication Settings

<URL>:_authToken

レジストリにアクセスするときに使用する認証用の Bearer トークンを指定します。例:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

環境変数を使用することもできます。例:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Environment variables are only expanded in user-level auth files, not in the project-level .npmrc. See Environment variables in auth settings.

Scope-specific auth tokens

Added in: v11.7.0

pnpm can use different auth tokens for different package scopes, even when those scopes point to the same registry URL. Add the package scope after the registry URL in the auth key:

@org-a:registry=https://npm.pkg.github.com/
@org-b:registry=https://npm.pkg.github.com/

//npm.pkg.github.com/:@org-a:_authToken=ORG_A_TOKEN
//npm.pkg.github.com/:@org-b:_authToken=ORG_B_TOKEN

//npm.pkg.github.com/:_authToken=FALLBACK_TOKEN

When installing or publishing @org-a/*, pnpm uses ORG_A_TOKEN; for @org-b/*, it uses ORG_B_TOKEN. Optionally, packages without a matching scope fall back to the registry-wide token (FALLBACK_TOKEN above), when provided.

pnpm login --registry=https://npm.pkg.github.com --scope=@org-a writes the token to the same scope-specific auth key.

This is useful for registries (such as GitHub Packages) that issue tokens per organization or per scope. Previously, auth was selected only by registry URL, so two scopes sharing a registry had to share a token.

<URL>:tokenHelper

tokenHelper とは、アクセストークンを出力する実行ファイルです。これは、authToken が一定値ではなく定期的に更新されるような場合に使用します。スクリプトやその他のツールが、既存のリフレッシュトークンを使って新しいアクセストークンを取得できるようになります。

helper へのパスの設定は、引数なしの絶対パスである必要があります。安全性を高めるため、この値はユーザーの .npmrc にのみ設定することが許されています。そうしないと、プロジェクトがプロジェクトのローカルの .npmrc に値を置いて、任意の実行ファイルを実行することができてしまいます。

デフォルトのレジストリに tokenHelper を設定します：

tokenHelper=/home/ivan/token-generator

指定されたレジストリに tokenHelper を設定します：

//registry.corp.com:tokenHelper=/home/ivan/token-generator

Certificate Settings

ca

デフォルト: npm CA 証明書
タイプ: String, Array, null

レジストリへのSSL接続をするのに信用する署名用CA証明書を指定します。値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。例:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Null に設定すると、既知の登録者のみを許可できます。もしくは、特定の CA 証明書の署名のみを信頼するように設定できます。

証明書の配列を指定することで、複数の信頼する CA を指定することもできます。

ca[]="..."
ca[]="..."

cafile

デフォルト: null
タイプ: path

ひとつ、もしくは複数のCA 署名用証明書を持つファイルへのパスを指定します。 ca 設定と同様ですが、複数の CA に関する情報を CLI 経由ではなくファイルに保持しておくことができます。

<URL>:cafile

Define the path to a Certificate Authority file to use when accessing the specified registry. 例:

//registry.npmjs.org/:cafile=ca-cert.pem

<URL>:ca

Added in: v10.25.0

Define an inline Certificate Authority certificate for the specified registry. The value must be PEM-encoded, like the global ca setting, but it only applies to the matching registry URL.

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

cert

デフォルト: null
タイプ: String

レジストリにアクセスするときに渡すクライアント証明書。値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。例:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

It is not the path to a certificate file.

<URL>:cert

Added in: v10.25.0

Define an inline client certificate to use when accessing the specified registry. 例:

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:certfile

Define the path to a certificate file to use when accessing the specified registry. 例:

//registry.npmjs.org/:certfile=server-cert.pem

key

デフォルト: null
タイプ: String

レジストリにアクセスするときに渡すクライアントキー。値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。例:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

It is not the path to a key file. Use <URL>:keyfile if you need to reference the file system instead of inlining the key.

この設定には機密情報が含まれています。リポジトリにコミットされたローカルの .npmrc ファイルに書き込まないでください。

<URL>:key

Added in: v10.25.0

Define an inline client key for the specified registry URL.

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:keyfile

Define the path to a client key file to use when accessing the specified registry. 例:

//registry.npmjs.org/:keyfile=server-key.pem

Auth file locations​

Environment variables in auth settings​

Authentication Settings​

<URL>:_authToken​

Scope-specific auth tokens​

<URL>:tokenHelper​

Certificate Settings​

ca​

cafile​

<URL>:cafile​

<URL>:ca​

cert​

<URL>:cert​

<URL>:certfile​

key​

<URL>:key​

<URL>:keyfile​

Auth file locations

Environment variables in auth settings

Authentication Settings

<URL>:_authToken

Scope-specific auth tokens

<URL>:tokenHelper

Certificate Settings

ca

cafile

<URL>:cafile

<URL>:ca

cert

<URL>:cert

<URL>:certfile

key

<URL>:key

<URL>:keyfile