pnpm Introduces New Lockfile Format to Reduce Git Merge Conflicts

pnpm has introduced an experimental lockfile format designed to reduce Git merge conflicts by changing how dependencies are recorded.

  • Sarah Gooding
2 min read
pnpm Introduces New Lockfile Format to Reduce Git Merge Conflicts

pnpm has introduced an experimental lockfile format designed to reduce Git merge conflicts by changing how dependency relationships are recorded. The new format, available starting with pnpm 12.19.0, previews changes planned for pnpm 13 and is available as an opt-in setting.

The change addresses a common frustration in JavaScript development, particularly in projects with multiple contributors or large dependency trees. Updates to dependencies can produce substantial changes in pnpm-lock.yaml, creating merge conflicts when developers work on separate branches.

The new format aims to reduce those conflicts by keeping related dependency information together and limiting the number of lines affected when peer dependencies change.

A New Structure for Dependency Relationships

#

The existing v9 lockfile format uses separate packages and snapshots sections to store package metadata and resolved dependency relationships. The experimental v13 format consolidates that information into a single packages section. The top-level importers section is also renamed to projects.

Package references now use bare version numbers rather than identifiers containing peer dependency or patch suffixes. Peer dependency bindings are represented through with mappings, while optional peers use a new notation. Registry package integrity hashes also move directly onto package entries.

These changes reduce the number of entries that need to be modified when dependencies change, particularly when updating peer dependencies.

The format also introduces JSON-like syntax with tabs and trailing commas, although the file remains valid YAML. As pnpm clarified on X, the reduction in Git conflicts comes from the structural changes, not the syntax.

Experimental Support Ahead of pnpm 13

#

The new format was introduced in pnpm 12.19.0 on November 10, 2026. Subsequent releases have continued refining its behavior.

Version 12.20.0 added support for recording dependency specifiers of local directory packages and addressed issues involving peer dependency cycles. Version 12.21.0 fixed additional problems involving lockfile generation, injected workspace packages, and frozen installations.

Developers can enable the format by adding the following setting to pnpm-workspace.yaml:

YAML
lockfile:
  format: v13

The default remains v9. Once enabled, pnpm writes the new format when resolving dependencies or when developers run pnpm install --lockfile-only.

According to the pnpm documentation, versions supporting the setting can read both formats, regardless of which format is configured for writing.

However, older pnpm versions that predate the setting cannot read v13 lockfiles. The project also cautions that the experimental format may change before pnpm 13 is released, potentially requiring developers to regenerate their lockfiles after upgrading.

Compatibility Implications for the JavaScript Ecosystem

#

The changes also affect tools that rely on lockfiles to reconstruct dependency graphs, including security scanners, software composition analysis platforms, and software bill of materials (SBOM) generators.

Although v13 remains valid YAML, tools that expect separate packages and snapshots sections, parse peer dependency information from package identifiers, or read integrity hashes from resolution objects may need updates.

Successfully parsing a lockfile does not guarantee that a tool can accurately reconstruct its dependencies. Incompatible tools could omit packages, misidentify resolved versions, or fail to process the dependency graph, potentially affecting vulnerability detection and other supply chain analysis.

The new format does not introduce additional security protections. Its primary purpose is to reduce merge conflicts, but its eventual adoption as the default in pnpm 13 will require compatible tooling across the JavaScript ecosystem.

Stay ahead of threats

Subscribe to our newsletter

Get notified when we publish new security blog posts!