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

  • Default: isolated
  • Type: isolated, hoisted, pnp

Node.js のパッケージをインストールするのに使用するリンカーを指定します。

  • isolated - dependencies are symlinked from a virtual store at node_modules/.pnpm.
  • hoisted - a flat node_modules without symlinks is created. Same as the node_modules created by npm or Yarn Classic. Legitimate reasons to use this setting:
    1. Your tooling doesn't work well with symlinks. A React Native project will most probably only work if you use a hoisted node_modules.
    2. Your project is deployed to a serverless hosting provider. Some serverless providers (for instance, AWS Lambda) don't support symlinks. An alternative solution for this problem is to bundle your application before deployment.
    3. If you want to publish your package with "bundledDependencies".
    4. If you are running Node.js with the --preserve-symlinks flag.
  • pnp - no node_modules. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. pnp をリンカーとして使う場合には、 symlinkfalse に設定することが推奨されます。

追加されたバージョン: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 ディレクトリがマウントされている場合に有用です。 There is an experimental CLI that allows you to mount a modules directory with FUSE: @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>:tokenHelper

Added in: v6.25.0

A token helper is an executable which outputs an auth token. This can be used in situations where the authToken is not a constant value but is something that refreshes regularly, where a script or other tool can use an existing refresh token to obtain a new access token.

The configuration for the path to the helper must be an absolute path, with no arguments. In order to be secure, it is only permitted to set this value in the user .npmrc. Otherwise a project could place a value in a project's local .npmrc and run arbitrary executables.

Setting a token helper for the default registry:

tokenHelper=/home/ivan/token-generator

Setting a token helper for the specified registry:

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

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

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.

maxsockets

Added in: v6.18.0

  • Default: network-concurrency x 3
  • タイプ: Number

The maximum number of connections to use per origin (protocol/host/port combination).

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 リクエストが完了するまでに待つ最大の時間。

Peer Dependency Settings

auto-install-peers

Added in: v6.26.0

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

When true, pnpm add <pkg> automatically installs any missing peer dependencies as dev dependencies.

strict-peer-dependencies

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

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

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

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.

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.

Node.js Settings

use-node-version

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

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

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

node-mirror:<releaseDir>

Added in: v6.24.0

  • Default: https://nodejs.org/download/<releaseDir>/
  • Type: URL

Sets the base URL for downloading Node.js. The <releaseDir> portion of this setting can be any directory from https://nodejs.org/download: release, rc, nightly, v8-canary, etc.

Here is how pnpm may be configured to download Node.js from Node.js mirror in China:

node-mirror:release=https://npmmirror.com/mirrors/node/
node-mirror:rc=https://npmmirror.com/mirrors/node-rc/
node-mirror:nightly=https://npmmirror.com/mirrors/node-nightly/

その他の設定

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 foo@2 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 package@version 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

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

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

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

cache-dir

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

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

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

use-stderr

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

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

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

extend-node-path

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

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

When false, the NODE_PATH environment variable is not set in the command shims. It is recommended to set this setting to false if you are getting the next error, when running commands:

The input line is too long. The syntax of the command is incorrect.