Settings (pnpm-workspace.yaml)
pnpm gets its configuration from the command line, environment variables, pnpm-workspace.yaml
, and
.npmrc
files.
The pnpm config
command can be used to read and edit the contents of the project and global configuration files.
The relevant configuration files are:
- Per-project configuration file:
/path/to/my/project/pnpm-workspace.yaml
- Global configuration file:
~/.config/pnpm/rc
(an INI-formatted list ofkey = value
parameters)
Authorization-related settings are handled by npm's configuration system. So, pnpm config set registry=<value>
will actually save the setting to npm's global configuration file.
Values in the configuration files may contain env variables using the ${NAME}
syntax. The env variables may also be specified with default values. Using ${NAME-fallback}
will return fallback
if NAME
isn't set. ${NAME:-fallback}
will return fallback
if NAME
isn't set, or is an empty string.
Dependency Resolution
overrides
This field allows you to instruct pnpm to override any dependency in the dependency graph. This is useful for enforcing all your packages to use a single version of a dependency, backporting a fix, replacing a dependency with a fork, or removing an unused dependency.
Note that the overrides field can only be set at the root of the project.
An example of the overrides
field:
overrides:
"foo": "^1.0.0"
"quux": "npm:@myorg/quux@^1.0.0"
"bar@^2.1.0": "3.0.0"
"qar@1>zoo": "2"
You may specify the package the overridden dependency belongs to by
separating the package selector from the dependency selector with a ">", for
example qar@1>zoo
will only override the zoo
dependency of qar@1
, not for
any other dependencies.
An override may be defined as a reference to a direct dependency's spec.
This is achieved by prefixing the name of the dependency with a $
:
{
"dependencies": {
"foo": "^1.0.0"
}
}
overrides:
foo: "$foo"
The referenced package does not need to match the overridden one:
overrides:
bar: "$foo"
If you find that your use of a certain package doesn't require one of its dependencies, you may use -
to remove it. For example, if package foo@1.0.0
requires a large package named bar
for a function that you don't use, removing it could reduce install time:
overrides:
"foo@1.0.0>bar": "-"
This feature is especially useful with optionalDependencies
, where most optional packages can be safely skipped.
packageExtensions
The packageExtensions
fields offer a way to extend the existing package definitions with additional information. For example, if react-redux
should have react-dom
in its peerDependencies
but it has not, it is possible to patch react-redux
using packageExtensions
:
packageExtensions:
react-redux:
peerDependencies:
react-dom: "*"
The keys in packageExtensions
are package names or package names and semver ranges, so it is possible to patch only some versions of a package:
packageExtensions:
react-redux@1:
peerDependencies:
react-dom: "*"
The following fields may be extended using packageExtensions
: dependencies
, optionalDependencies
, peerDependencies
, and peerDependenciesMeta
.
A bigger example:
packageExtensions:
express@1:
optionalDependencies:
typescript: "2"
fork-ts-checker-webpack-plugin:
dependencies:
"@babel/core": "1"
peerDependencies:
eslint: ">= 6"
peerDependenciesMeta:
eslint:
optional: true
Together with Yarn, we maintain a database of packageExtensions
to patch broken packages in the ecosystem.
If you use packageExtensions
, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions
database.
allowedDeprecatedVersions
This setting allows muting deprecation warnings of specific packages.
Пример:
allowedDeprecatedVersions:
express: "1"
request: "*"
With the above configuration pnpm will not print deprecation warnings about any version of request
and about v1 of express
.
updateConfig
updateConfig.ignoreDependencies
Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated
command and updated, when running pnpm update --latest
. However, you may list packages that you don't want to upgrade in the ignoreDependencies
field:
updateConfig:
ignoreDependencies:
- load-json-file
Patterns are also supported, so you may ignore any packages from a scope: @babel/*
.
supportedArchitectures
You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.
For example, the following configuration tells to install optional dependencies for Windows x64:
supportedArchitectures:
os:
- win32
cpu:
- x64
Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:
supportedArchitectures:
os:
- win32
- darwin
- current
cpu:
- x64
- arm64
Additionally, supportedArchitectures
also supports specifying the libc
of the system.
ignoredOptionalDependencies
If an optional dependency has its name included in this array, it will be skipped. For example:
ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"
Dependency Hoisting Settings
hoist
- Default: true
- Type: boolean
When true
, all dependencies are hoisted to node_modules/.pnpm/node_modules
. This makes
unlisted dependencies accessible to all packages inside node_modules
.
hoistWorkspacePackages
- Default: true
- Type: boolean
When true
, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules
or to <workspace_root>/node_modules
depending on other hoisting settings (hoistPattern
and publicHoistPattern
).
hoistPattern
- Default: ['*']
- Type: string[]
Tells pnpm which packages should be hoisted to node_modules/.pnpm/node_modules
. By
default, all packages are hoisted - however, if you know that only some flawed
packages have phantom dependencies, you can use this option to exclusively hoist
the phantom dependencies (recommended).
For instance:
hoistPattern:
- "*eslint*"
- "*babel*"
You may also exclude patterns from hoisting using !
.
For instance:
hoistPattern:
- "*types*"
- "!@types/react"
publicHoistPattern
- Default: []
- Type: string[]
Unlike hoistPattern
, which hoists dependencies to a hidden modules directory
inside the virtual store, publicHoistPattern
hoists dependencies matching
the pattern to the root modules directory. Hoisting to the root modules
directory means that application code will have access to phantom dependencies,
even if they modify the resolution strategy improperly.
This setting is useful when dealing with some flawed pluggable tools that don't resolve dependencies properly.
For instance:
publicHoistPattern:
- "*plugin*"
Note: Setting shamefullyHoist
to true
is the same as setting
publicHoistPattern
to *
.
You may also exclude patterns from hoisting using !
.
For instance:
publicHoistPattern:
- "*types*"
- "!@types/react"
shamefullyHoist
- Default: false
- Type: Boolean
By default, pnpm creates a semistrict node_modules
, meaning dependencies have
access to undeclared dependencies but modules outside of node_modules
do not.
With this layout, most of the packages in the ecosystem work with no issues.
However, if some tooling only works when the hoisted dependencies are in the
root of node_modules
, you can set this to true
to hoist them for you.
Node-Modules Settings
modulesDir
- Default: node_modules
- Type: path
The directory in which dependencies will be installed (instead of
node_modules
).
nodeLinker
- Default: isolated
- Type: isolated, hoisted, pnp
Defines what linker should be used for installing Node packages.
- isolated - dependencies are symlinked from a virtual store at
node_modules/.pnpm
. - hoisted - a flat
node_modules
without symlinks is created. Same as thenode_modules
created by npm or Yarn Classic. One of Yarn's libraries is used for hoisting, when this setting is used. Legitimate reasons to use this setting:- Your tooling doesn't work well with symlinks. A React Native project will most probably only work if you use a hoisted
node_modules
. - 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.
- If you want to publish your package with
"bundledDependencies"
. - If you are running Node.js with the --preserve-symlinks flag.
- Your tooling doesn't work well with symlinks. A React Native project will most probably only work if you use a hoisted
- pnp - no
node_modules
. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. It is recommended to also setsymlink
setting tofalse
when usingpnp
as your linker.
symlink
- Default: true
- Type: Boolean
When symlink
is set to false
, pnpm creates a virtual store directory without
any symlinks. It is a useful setting together with nodeLinker=pnp
.
enableModulesDir
- Default: true
- Type: Boolean
When false
, pnpm will not write any files to the modules directory
(node_modules
). This is useful for when the modules directory is mounted with
filesystem in userspace (FUSE). There is an experimental CLI that allows you to
mount a modules directory with FUSE: @pnpm/mount-modules.
virtualStoreDir
- Default: node_modules/.pnpm
- Types: path
The directory with links to the store. All direct and indirect dependencies of the project are linked into this directory.
This is a useful setting that can solve issues with long paths on Windows. If
you have some dependencies with very long paths, you can select a virtual store
in the root of your drive (for instance C:\my-project-store
).
Or you can set the virtual store to .pnpm
and add it to .gitignore
. This
will make stacktraces cleaner as paths to dependencies will be one directory
higher.
NOTE: the virtual store cannot be shared between several projects. Every project should have its own virtual store (except for in workspaces where the root is shared).
virtualStoreDirMaxLength
- По умолчанию:
- On Linux/macOS: 120
- On Windows: 60
- Types: number
Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm
). You may set this to a lower number if you encounter long path issues on Windows.
packageImportMethod
- Default: auto
- Type: auto, hardlink, copy, clone, clone-or-copy
Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules
, then you need to change the nodeLinker setting, not this one).
- auto - try to clone packages from the store. If cloning is not supported then hardlink packages from the store. If neither cloning nor linking is possible, fall back to copying
- hardlink - hard link packages from the store
- clone-or-copy - try to clone packages from the store. If cloning is not supported then fall back to copying
- copy - copy packages from the store
- clone - clone (AKA copy-on-write or reference link) packages from the store
Cloning is the best way to write packages to node_modules. It is the fastest way and safest way. When cloning is used, you may edit files in your node_modules and they will not be modified in the central content-addressable store.
Unfortunately, not all file systems support cloning. We recommend using a copy-on-write (CoW) file system (for instance, Btrfs instead of Ext4 on Linux) for the best experience with pnpm.
modulesCacheMaxAge
- Default: 10080 (7 days in minutes)
- Type: number
The time in minutes after which orphan packages from the modules directory should be removed. pnpm keeps a cache of packages in the modules directory. This boosts installation speed when switching branches or downgrading dependencies.
dlxCacheMaxAge
- Default: 1440 (1 day in minutes)
- Type: number
The time in minutes after which dlx cache expires. After executing a dlx command, pnpm keeps a cache that omits the installation step for subsequent calls to the same dlx command.
enableGlobalVirtualStore
Added in: v10.12.1
- Default: false (always false in CI)
- Type: Boolean
- Status: Experimental
When enabled, node_modules
contains only symlinks to a central virtual store, rather than to node_modules/.pnpm
. By default, this central store is located at <store-path>/links
(use pnpm store path
to find <store-path>
).
In the central virtual store, each package is hard linked into a directory whose name is the hash of its dependency graph. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how NixOS manages packages, using dependency graph hashes to create isolated and shareable package directories in the Nix store.
This should not be confused with the global content-addressable store. The actual package files are still hard linked from the content-addressable store—but instead of being linked directly into
node_modules/.pnpm
, they are linked into the global virtual store.
Using a global virtual store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.
To support hoisted dependencies when using a global virtual store, pnpm relies on the NODE_PATH
environment variable. This allows Node.js to resolve packages from the hoisted node_modules
directory. However, this workaround does not work with ESM modules, because Node.js no longer respects NODE_PATH
when using ESM.
If your dependencies are ESM and they import packages not declared in their own package.json
(which is considered bad practice), you’ll likely run into resolution errors. There are two ways to fix this:
- Use packageExtensions to explicitly add the missing dependencies.
- Add the @pnpm/plugin-esm-node-path config dependency to your project. This plugin registers a custom ESM loader that restores
NODE_PATH
support for ESM, allowing hoisted dependencies to be resolved correctly.
Store Settings
storeDir
- По умолчанию:
- If the $PNPM_HOME env variable is set, then $PNPM_HOME/store
- If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/store
- On Windows: ~/AppData/Local/pnpm/store
- On macOS: ~/Library/pnpm/store
- On Linux: ~/.local/share/pnpm/store
- Type: path
The location where all the packages are saved on the disk.
The store should be always on the same disk on which installation is happening,
so there will be one store per disk. If there is a home directory on the current
disk, then the store is created inside it. If there is no home on the disk,
then the store is created at the root of the filesystem. For
example, if installation is happening on a filesystem mounted at /mnt
,
then the store will be created at /mnt/.pnpm-store
. The same goes for Windows
systems.
It is possible to set a store from a different disk but in that case pnpm will copy packages from the store instead of hard-linking them, as hard links are only possible on the same filesystem.
verifyStoreIntegrity
- Default: true
- Type: Boolean
By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules
. If verifyStoreIntegrity
is set to false
, files in the content-addressable store will not be checked during installation.
useRunningStoreServer
Deprecated feature
- Default: false
- Type: Boolean
Only allows installation with a store server. If no store server is running, installation will fail.
strictStorePkgContentCheck
- Default: true
- Type: Boolean
Some registries allow the exact same content to be published under different package names and/or versions. This breaks the validity checks of packages in the store. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck
setting to false
.
Lockfile Settings
lockfile
- Default: true
- Type: Boolean
When set to false
, pnpm won't read or generate a pnpm-lock.yaml
file.
preferFrozenLockfile
- Default: true
- Type: 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.
lockfileIncludeTarballUrl
- Default: false
- Type: Boolean
Add the full URL to the package's tarball to every entry in pnpm-lock.yaml
.
gitBranchLockfile
- Default: false
- Type: Boolean
When set to true
, the generated lockfile name after installation will be named
based on the current branch name to completely avoid merge conflicts. For example,
if the current branch name is feature-foo
, the corresponding lockfile name will
be pnpm-lock.feature-foo.yaml
instead of pnpm-lock.yaml
. It is typically used
in conjunction with the command line argument --merge-git-branch-lockfiles
or by
setting mergeGitBranchLockfilesBranchPattern
in the pnpm-workspace.yaml
file.