1---
2name: pnpm-configuration
3description: Configuring pnpm via pnpm-workspace.yaml (settings), the global config.yaml, and .npmrc (auth only)
4---
5 
6# pnpm Configuration
7 
8pnpm settings are split into **two** categories. Knowing where each goes is the single most important config concept in current pnpm:
9 
10| Category | Stored in | Format |
11|----------|-----------|--------|
12| **All pnpm/install settings** (`nodeLinker`, `hoistPattern`, `autoInstallPeers`, `overrides`, `catalog`, …) | `pnpm-workspace.yaml` (project) and `config.yaml` (global) | YAML, **camelCase** keys |
13| **Auth & registry credentials** (`_authToken`, `cert`, `key`, …) | `.npmrc` (project, gitignored) and global `rc` | INI |
14 
15> **Important changes:** pnpm no longer reads settings from the `pnpm` field of `package.json`, and `.npmrc` is now used **only** for authentication/registry credentials. Everything else belongs in `pnpm-workspace.yaml`. Keys in YAML are **camelCase** (e.g. `nodeLinker`), not the kebab-case used by old `.npmrc` files.
16 
17## pnpm-workspace.yaml (primary config)
18 
19Place at the workspace/project root. Even a single-package project uses this file for pnpm settings.
20 
21```yaml title="pnpm-workspace.yaml"
22# Workspace packages (omit for a single-package repo)
23packages:
24  - 'packages/*'
25  - 'apps/*'
26  - '!**/test/**'
27 
28# Common install settings (camelCase)
29nodeLinker: isolated          # isolated (default) | hoisted | pnp
30autoInstallPeers: true
31strictPeerDependencies: false
32savePrefix: '^'
33saveExact: false
34hoistPattern:
35  - '*eslint*'
36  - '*babel*'
37publicHoistPattern: []
38shamefullyHoist: false
39dedupeDirectDeps: false
40resolutionMode: highest       # highest | time-based | lowest-direct
41 
42# Centralized version management
43catalog:
44  react: ^18.2.0
45 
46# Force dependency versions (root only)
47overrides:
48  lodash: ^4.17.21
49  'foo@^1.0.0>bar': ^2.0.0
50 
51# Extend/patch broken package manifests
52packageExtensions:
53  react-redux:
54    peerDependencies:
55      react-dom: '*'
56 
57# Peer dependency rules
58peerDependencyRules:
59  ignoreMissing:
60    - '@babel/*'
61  allowedVersions:
62    react: '17 || 18'
63```
64 
65## Global configuration (config.yaml)
66 
67User-level non-auth settings live in a global YAML `config.yaml`:
68 
69- `$XDG_CONFIG_HOME/pnpm/config.yaml` (if set)
70- Linux: `~/.config/pnpm/config.yaml`
71- macOS: `~/Library/Preferences/pnpm/config.yaml`
72- Windows: `~/AppData/Local/pnpm/config/config.yaml`
73 
74The companion global `rc` file (same directory, named `rc`) holds only registry/auth settings.
75 
76## Per-project settings in a workspace (packageConfigs)
77 
78There are no per-subproject `.npmrc` files anymore. Set per-package config via `packageConfigs` in the root `pnpm-workspace.yaml`:
79 
80```yaml title="pnpm-workspace.yaml"
81packageConfigs:
82  # Map form: keyed by package name
83  project-1:
84    saveExact: true
85  project-2:
86    savePrefix: '~'
87  # Array form: pattern-matched rules
88  # - match: ['project-1', 'project-2']
89  #   modulesDir: node_modules
90  #   saveExact: true
91```
92 
93## .npmrc — authentication only
94 
95Keep auth tokens out of the repo (gitignore the project `.npmrc`). Auth files, highest priority first:
96 
971. `<workspace root>/.npmrc` (project, gitignored)
982. `<pnpm config>/auth.ini` (written by `pnpm login`)
993. `~/.npmrc` (fallback for npm compatibility)
100 
101```ini title=".npmrc"
102//registry.npmjs.org/:_authToken=${NPM_TOKEN}
103@myorg:registry=https://npm.myorg.com/
104//npm.myorg.com/:_authToken=${MYORG_TOKEN}
105```
106 
107Configure registries themselves (non-secret) in `pnpm-workspace.yaml`:
108 
109```yaml title="pnpm-workspace.yaml"
110registries:
111  default: https://registry.npmjs.org/
112  '@my-org': https://private.example.com/
113# Named registry aliases usable as a prefix, e.g. `pnpm add work:@corp/lib`
114namedRegistries:
115  work: https://npm.work.example.com/
116```
117 
118> Security: since v11, env-variable expansion is disabled for registry/proxy URLs and credential keys in the **project** `.npmrc` (to stop a malicious repo from leaking secrets). Put dynamic-token lines in the user-level auth file instead.
119 
120## The `pnpm config` command
121 
122```bash
123# Writes to global config.yaml / rc by default
124pnpm config set nodeVersion 22.0.0
125pnpm config set --location=project nodeVersion 22.0.0   # writes pnpm-workspace.yaml
126 
127# JSON values create arrays/objects
128pnpm config set --location=project --json allowBuilds '{"react": true}'
129 
130# get/list print JSON (no longer INI) since v11
131pnpm config get nodeLinker
132pnpm config get 'allowBuilds.react'
133pnpm config list
134```
135 
136## Environment variables
137 
138Use `pnpm_config_*` (or `PNPM_CONFIG_*`). pnpm **no longer reads `npm_config_*`**.
139 
140```bash
141pnpm_config_save_exact=true pnpm add foo
142```
143 
144## Notable settings that changed names
145 
146| Old (removed) | Replacement | Notes |
147|---------------|-------------|-------|
148| `onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile` | `allowBuilds: { name: true\|false }` | Single map controlling build-script approval. See supply-chain-security. |
149| `managePackageManagerVersions`, `packageManagerStrict`, `packageManagerStrictVersion`, `COREPACK_ENABLE_STRICT` | `pmOnFail: download\|ignore\|warn\|error` | Behavior when running pnpm version ≠ declared one. |
150| `useNodeVersion` | `devEngines.runtime` (in `package.json`) | Runtime pinning. |
151| `auditConfig.ignoreCves` | `auditConfig.ignoreGhsas` | Use GHSA IDs. |
152| `allowNonAppliedPatches` | `allowUnusedPatches` | `ignorePatchFailures` removed (patches now always throw). |
153| `package.json#pnpm` field | `pnpm-workspace.yaml` | No longer read at all. |
154 
155## Package Manager / Runtime pinning (package.json)
156 
157```json
158{
159  "packageManager": "[email protected]",
160  "devEngines": {
161    "packageManager": { "name": "pnpm", "version": ">=11.0.0 <12.0.0", "onFail": "download" },
162    "runtime": { "name": "node", "version": "22.x", "onFail": "download" }
163  }
164}
165```
166 
167`devEngines.packageManager` supports ranges (resolved version stored in lockfile); `packageManager` requires an exact version. Override `onFail` without editing the manifest via `pmOnFail` / `runtimeOnFail` settings.
168 
169## Key Points
170 
171- All pnpm settings go in `pnpm-workspace.yaml` (camelCase) or global `config.yaml`; `.npmrc` is auth/registry only.
172- `package.json#pnpm` and `npm_config_*` env vars are no longer read.
173- Use `packageConfigs` for per-package settings inside a workspace.
174- Build-script approval is now one `allowBuilds` map; package-manager strictness is one `pmOnFail` setting.
175- `pnpm config get`/`list` output JSON, and `--location=project` writes to `pnpm-workspace.yaml`.
176 
177<!--
178Source references:
179- https://pnpm.io/settings
180- https://pnpm.io/configuring
181- https://pnpm.io/npmrc
182- https://pnpm.io/pnpm-workspace_yaml
183- https://pnpm.io/package_json
184- https://pnpm.io/cli/config
185-->
186