Does pnpm lockfile format upgrade affect repeatable installs across CLI versions?

Answer

Yes – a lockfile written by a newer pnpm major version may not produce exactly the same node_modules layout when read by an older pnpm client, because the lockfile format can change and the node-linker setting is not stored in the lockfile.

Confirmed facts

• pnpm guarantees identical resolution when the same lockfile is used with the same pnpm major version and the same node-linker setting.
• The lockfileVersion field indicates the format; older clients can read lower versions but may ignore or misinterpret newer fields, altering hoisting.
• The node-linker choice (hoisted, isolated, virtual) is not recorded in pnpm-lock.yaml; it must be set via .npmrc or CLI.
• pnpm does not automatically bump lockfileVersion when a newer CLI is used; it preserves the existing format for backward compatibility and only upgrades when a command that requires a newer format is run (e.g., pnpm install --lockfile-only when a new feature is invoked).

Steps to ensure repeatable installs

1. Check the lockfile version:

   grep lockfileVersion pnpm-lock.yaml

2. Pin the pnpm major version in CI and developer environments (e.g., via engines.pnpm in package.json or a .npmrc engine-strict setting).
3. Fix the node-linker setting in a committed .npmrc (e.g., node-linker=hoisted) so all clients use the same layout.
4. Run pnpm install with that locked version and compare node_modules checksums if you need to verify.

Missing diagnostic detail

If you are seeing divergent installs despite matching lockfile and linker, confirm the exact pnpm version used (pnpm -v) on each machine; a patch-level difference that changes hoisting heuristics could be the cause.