Skip to main content
Version: 6.x

.npmrc

pnpm は、コマンド行、環境変数、および .npmrc ファイルから設定を取得します。

pnpm config コマンドを使用して、ユーザーおよびグローバルの .npmrc ファイルの内容を更新および編集することができます。

関連する4つのファイルは次のとおりです。

  • プロジェクトごとの設定ファイル(/path/to/my/project/.npmrc)
  • ワークスペースごとの設定ファイル (pnpm-workspace.yaml ファイルが含まれているディレクトリー)
  • ユーザーごとの設定ファイル(~/.npmrc)
  • グローバルな設定ファイル (/etc/npmrc)

.npmrc ファイルはすべて key = value という INI形式 のパラメータのリストです。

依存の巻き上げ設定#

hoist#

追加されたバージョン:v4.0.0

  • デフォルト: true
  • タイプ: boolean

trueの場合、すべての依存関係は node_modules/.pnpm に巻き上げられます。 これにより、リストされていない依存に、 node_modules 内のすべてのパッケージからアクセスできるようになります。

hoist-pattern#

追加されたバージョン:v4.0.0

  • デフォルト: ['*']
  • タイプ: string[]

どのパッケージを node_modules/.pnpm に巻き上げるかを指定します。 デフォルトでは、全てのパッケージが巻き上げられます。しかし、非常に多くの依存を持つ、扱いに困るパッケージについてわかっている場合には、このオプションにより、それらを省いて巻き上げするように指定することができます。 (推奨)

例:

hoist-pattern[]=*eslint*hoist-pattern[]=*babel*

public-hoist-pattern#

追加されたバージョン:v5.2.0

  • デフォルト: ['*types*', '*eslint*', '@prettier/plugin-*', '*prettier-plugin-*']
  • タイプ: string[]

hoist-pattern が仮想ストア内の隠し node_modules ディレクトリに依存を巻き上げるのに対し、public-hoist-pattern はパターンにマッチする依存をルートの node_modules ディレクトリへと巻き上げます。 ルートの node_modules ディレクトリに巻き上げると、アプリケーションのコードは、たとえ依存解決方法を不適切なものに変更されていたとしても、それらの巻き上げられた非常に大量の依存へアクセスできることになります。

この設定は、いくつかのプラグイン機構を持った、依存を適切に解決しない、扱いに困るツールを扱う際に役立ちます。

例:

public-hoist-pattern[]=*plugin*

注意: shamefully-hoisttrue に設定するのと public-hoist-pattern* に設定するのは同じ効果があります。

shamefully-hoist#

追加されたバージョン: v1.34.0 で shamefully-flatten として追加され、v4.0.0 で名前が変更されました。

  • デフォルト: false
  • タイプ: Boolean

デフォルトでは、pnpm はそれなりに厳格な node_modules を作成します。依存パッケージは定義されない依存へのアクセスをすることが可能なまま、node_modules の外からはアクセスできないようになっています。 この方式では、ほとんどのパッケージがそのエコシステムの中で問題なく機能します。 ただし、いくつかのツールが、依存がルートの node_modules に 巻き上げられている場合にのみ機能する場合には、この設定を true にすることでそのように巻き上げることができます。

node_modules に関する設定#

store-dir#

追加されたバージョン: v4.2.0 で store として追加されました

  • デフォルト: ~/.pnpm-store
  • タイプ: path

パッケージをディスク上のどこに保存するか指定します。

ストアはインストールを行うのと同じディスク状にある必要があります。つまり、ディスクごとに一つのストアを持つことになります。 現在のディスク状にホームディレクトリがある場合は、ストアは<home dir>/.pnpm-store に作られます。 もしディスク状にホームディレクトリがない場合は、ストアはファイルシステムのルートに作られます。 例えば、/mnt にマウントされたファイルシステム状でインストールを行なった場合、ストアは /mnt/.pnpm-store に作られます。 Windows システムでも同様です。

異なるディスク状のストアを指定することも可能ですが、その場合 pnpm はハードリンクをせずにパッケージをコピーします。これは、ハードリンクは同一のファイルシステム状でのみ可能なためです。

modules-dir#

追加されたバージョン:v4.14.0

  • デフォルト: node_modules
  • タイプ: path

node_modules の代わりに依存をインストールする場所を指定します。

node-linker#

追加されたバージョン:v5.9.0

  • デフォルト: undefined
  • タイプ: undefined, pnp

Node.js のパッケージをインストールするのに使用するリンカーを指定します。 デフォルトでは、pnpm はリンク済みのモジュールディレクトリを作成しますが、プラグアンドプレイでビルドして解決する方法もサポートしています。 プラグアンドプレイ方式とは、Node.js にとって革新的な Yarn で用いられている 方法です。

pnp をリンカーとして使う場合には、 symlinkfalse に設定することが推奨されます。

symlink#

追加されたバージョン:v5.9.0

  • デフォルト: true
  • タイプ: Boolean

symlinkfalse に設定すると、pnpm は仮想ストアのディレクトリをシンボリックリンクを用いずに構成します。 この設定は node-linker=pnp と組み合わせる際に役立ちます。

enable-modules-dir#

追加されたバージョン:v5.15.0

  • デフォルト: false
  • タイプ: Boolean

false を設定すると、pnpm は node_modules ディレクトリにファイルを一切書き込みません。 この設定はユーザスペース上のファイルシステム (FUSE) に node_modules ディレクトリがマウントされている場合に有用です。 node_module ディレクトリを FUSE でマウントするのに使える実験的な CLI はこちら: @pnpm/mount-modules

virtual-store-dir#

追加されたバージョン:v4.1.0

  • デフォルト: node_modules/.pnpm
  • タイプ: path

ストアにリンクするディレクトリを指定する。 すべてのプロジェクトの直接および間接的な依存はこのディレクトリへリンクされる。

Windows 上でのパスの長さ上限に関する問題を解決するのに役立ちます。 何らかの非常に長いパスを持つ依存がある場合、ドライブ上のルートに仮想ストアを置くことが可能です。 (例: C:\my-project-store)

もしくは、仮想ストアを .pnpm にして .gitignore に追記することもできます。 依存のディレクトリをひとつ上にすることで、スタックトレース上での表示がすっきりします。

注意: 仮想ストアは複数のプロジェクト間で共有することはできません。 すべてのプロジェクトはそれぞれ固有の仮想ストアを持つ必要があります。 (ルートが共通のワークスペース内のプロジェクトは除く)

package-import-method#

追加されたバージョン:v1.25.0

  • デフォルト: auto
  • タイプ: auto, hardlink, copy, clone

パッケージがストアからインポートされる方法を制御します。

  • auto - ストアからパッケージをクローンしようとします。 クローンがサポートされていない場合、ストアからパッケージをハードリンクします。 クローンもリンクもできない場合は、コピーします。
  • hardlink - ストアからパッケージをハードリンクします。
  • copy - ストアからパッケージをハードリンクします。
  • clone - ストアからパッケージをクローンします。 (別名: copy-on-write、 参照リンク)

modules-cache-max-age#

追加されたバージョン:v6.0.0

  • デフォルト: 10080 (単位は分、7 日)
  • タイプ: number

孤立したパッケージを node_module ディレクトリから削除するまでの時間を分単位で指定します。 pnpm はパッケージのキャッシュを node_module ディレクトリに保持します。 これにより、ブランチを切り替えたり、依存のダウングレードを行う際のインストールのスピードを速くします。

ロックファイル設定#

lockfile#

Added in: v1.32.0 as shrinkwrap

  • デフォルト: true
  • タイプ: Boolean

When set to false, pnpm won't read or generate a pnpm-lock.yaml file.

prefer-frozen-lockfile#

Added in: v1.37.1 as prefer-frozen-shrinkwrap

  • Default: true (from v1.38.0)
  • タイプ: Boolean

When set to true and the available pnpm-lock.yaml satisfies the package.json dependencies directive, a headless installation is performed. A headless installation skips all dependency resolution as it does not need to modify the lockfile.

レジストリ & 認証設定#

registry#

The base URL of the npm package registry (trailing slash included).

<scope>:registry#

The npm registry that should be used for packages of the specified scope. For example, setting @babel:registry=https://example.com/packages/npm/ will enforce that when you use pnpm add @babel/core, or any @babel scoped package, the package will be fetched from https://example.com/packages/npm instead of the default registry.

<URL>:_authToken#

Define the authentication bearer token to use when accessing the specified registry. 例:

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

You may also use an environment variable. 例:

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

<URL>:always-auth#

  • デフォルト: false
  • タイプ: Boolean

Force pnpm to always require authentication (even for GET requests) when accessing the specified registry. 例:

@babel:registry=https://gitlab.com/api/v4/packages/npm///gitlab.com/api/v4/packages/npm/:always-auth=true
registry=https://registry.npmjs.org///registry.npmjs.org/:always-auth=true

リクエスト設定#

ca#

  • Default: The npm CA certificate
  • Type: String, Array or null

The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). 例:

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

Set to null to only allow known registrars, or to a specific CA cert to trust only that specific signing authority.

Multiple CAs can be trusted by specifying an array of certificates:

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

See also the strict-ssl config.

cafile#

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

A path to a file containing one or multiple Certificate Authority signing certificates. Similar to the ca setting, but allows for multiple CAs, as well as for the CA information to be stored in a file instead of being specified via CLI.

cert#

  • デフォルト: null
  • Type: String

A client certificate to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). 例:

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

It is not the path to a certificate file (and there is no certfile option).

https-proxy#

  • デフォルト: null
  • Type: url

A proxy to use for outgoing HTTPS requests. If the HTTPS_PROXY, https_proxy, HTTP_PROXY or http_proxy environment variables are set, their values will be used instead.

key#

  • デフォルト: null
  • Type: String

A client key to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). 例:

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

It is not the path to a key file (and there is no keyfile option).

local-address#

  • デフォルト: undefined
  • Type: IP Address

The IP address of the local interface to use when making connections to the npm registry. Must be IPv4 in versions of Node prior to 12.x.

proxy#

  • デフォルト: null
  • Type: url

A proxy to use for outgoing http requests. If the HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.

noproxy#

Added in: v5.18.8

  • デフォルト: null
  • Type: String

A comma-separated string of domain extensions that a proxy should not be used for.

strict-ssl#

  • デフォルト: true
  • タイプ: Boolean

Whether or not to do SSL key validation when making requests to the registry via HTTPS.

See also the ca option.

network-concurrency#

  • Default: 16
  • タイプ: Number

Controls the maximum number of HTTP(S) requests to process simultaneously.

fetch-retries#

  • Default: 2
  • タイプ: Number

How many times to retry if pnpm fails to fetch from the registry.

fetch-retry-factor#

  • Default: 10
  • タイプ: Number

The exponential factor for retry backoff.

fetch-retry-mintimeout#

  • Default: 10000 (10 seconds)
  • タイプ: Number

The minimum (base) timeout for retrying requests.

fetch-retry-maxtimeout#

  • Default: 60000 (1 minute)
  • タイプ: Number

The maximum fallback timeout to ensure the retry factor does not make requests too long.

fetch-timeout#

追加されたバージョン:v6.2.0

  • Default: 60000 (1 minute)
  • タイプ: Number

HTTP リクエストが完了するまでに待つ最大の時間。

CLI 設定#

[no-]color#

追加されたバージョン:v4.1.0

  • デフォルト: auto
  • Type: auto, always, never

Controls colors in the output.

  • auto - output uses colors when the standard output is a terminal or TTY.
  • always - ignore the difference between terminals and pipes. You’ll rarely want this; in most scenarios, if you want color codes in your redirected output, you can instead pass a --color flag to the pnpm command to force it to use color codes. The default setting is almost always what you’ll want.
  • never - turns off colors. This is the setting used by --no-color.

loglevel#

Added in: v4.13.0

  • Default: info
  • Type: debug, info, warn, error

Any logs at or higher than the given level will be shown. You can instead pass --silent to turn off all output logs.

strict-peer-dependencies#

Added in: v2.15.0

  • デフォルト: false
  • タイプ: Boolean

If this is enabled, commands will fail if there is a missing or invalid peer dependency in the tree.

use-beta-cli#

追加されたバージョン:v3.6.0

  • デフォルト: false
  • タイプ: Boolean

Experimental option that enables beta features of the CLI. This means that you may get some changes to the CLI functionality that are breaking changes, or potentially bugs.

recursive-install#

Added in: v5.4.0

  • デフォルト: true
  • タイプ: Boolean

If this is enabled, the primary behaviour of pnpm install becomes that of pnpm install -r, meaning the install is performed on all workspace or subdirectory packages.

Else, pnpm install will exclusively build the package in the current directory.

engine-strict#

  • デフォルト: false
  • タイプ: Boolean

If this is enabled, pnpm will not install any package that claims to not be compatible with the current Node version.

Regardless of this configuration, installation will always fail if a project (not a dependency) specifies an incompatible version in its engines field.

npm-path#

Added in: v4.8.0

  • タイプ: path

The location of the npm binary that pnpm uses for some actions, like publishing.

ビルド設定#

child-concurrency#

  • Default: 5
  • タイプ: Number

The maximum number of child processes to allocate simultaneously to build node_modules.

side-effects-cache#

Added in: v1.31.0

  • デフォルト: false
  • タイプ: Boolean
  • Stability: Experimental

Use and cache the results of (pre/post)install hooks.

side-effects-cache-readonly#

Added in: v1.31.0

  • デフォルト: false
  • タイプ: Boolean
  • Stability: Experimental

Only use the side effects cache if present, do not create it for new packages.

unsafe-perm#

  • Default: false IF running as root, ELSE true
  • タイプ: Boolean

Set to true to enable UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

その他の設定#

use-running-store-server#

Added in: v2.5.0

  • デフォルト: false
  • タイプ: Boolean

Only allows installation with a store server. If no store server is running, installation will fail.

save-prefix#

  • Default: '^'
  • Type: String

Configure how versions of packages installed to a package.json file get prefixed.

For example, if a package has version 1.2.3, by default its version is set to ^1.2.3 which allows minor upgrades for that package, but after pnpm config set save-prefix='~' it would be set to ~1.2.3 which only allows patch upgrades.

This setting is ignored when the added package has a range specified. For instance, pnpm add [email protected] will set the version of foo in package.json to 2, regardless of the value of save-prefix.

tag#

  • Default: latest
  • Type: String

If you pnpm add a package and you don't provide a specific version, then it will install the package at the version registered under the tag from this setting.

This also sets the tag that is added to the [email protected] specified by the pnpm tag command if no explicit tag is given.

global-dir#

Added in: v4.2.0

  • Default: <path to node>/pnpm-global
  • タイプ: path

Specify a custom directory to store global packages.

global-bin-dir#

Added in: v6.15.0

Allows to set the target directory for the bin files of globally installed packages.

state-dir#

Added in: v6.10.0

  • デフォルト: $XDG_STATE_HOME/pnpm
  • タイプ: path

pnpm が pnpm-state.json ファイルを作成するディレクトリを指定します。これは現時点ではアップデートのチェックにのみ使用されています。

cache-dir#

Added in: v6.10.0

  • デフォルト: $XDG_CACHE_HOME/pnpm
  • タイプ: path

パッケージメタデータのキャッシュを置く場所を指定します。

use-node-version#

Added in: v6.5.0

  • デフォルト: undefined
  • タイプ: semver

プロジェクトのランタイムとして使う Node.js の正確なバージョンを指定します。 pnpm は自動で指定されたバージョンの Node.js をインストールして pnpm runpnpm node を実行する際に使用します。

use-stderr#

Added in: v6.5.0

  • デフォルト: false
  • タイプ: Boolean

true に設定すると、すべての出力は標準エラーに書き込まれます。