Lockfile format
This page specifies the contents of a pnpm-lock.yaml document: its keys,
the grammar of its package keys, and how its entries reference each other.
It is for tools that parse the lockfile. Reading pnpm-lock.yaml
covers how to split the file into documents, which documents a tool needs, and
which hash integrity pins.
This page covers the default v9 format, including the boot and project
documents. See lockfile.format for the
experimental v13 format. The examples use made-up package names.
Overview#
A lockfile document records three layers:
| Key | Records | Keyed by |
|---|---|---|
importers |
The direct dependencies of each project | Project directory |
packages |
Facts about a package version that do not depend on where it is installed | Package key without suffixes |
snapshots |
The resolved dependencies for a package in a particular peer context | Full package key |
A project's dependency points to a snapshot. A snapshot's dependencies point to
other snapshots. Each snapshot has one packages entry, and several snapshots
can share it.
lockfileVersion: '9.0'
settings:
autoInstallPeers: true
excludeLinksFromLockfile: false
importers:
.:
dependencies:
plugin:
specifier: ^2.0.0
version: 2.1.0(host@5.0.0)
host:
specifier: ^5.0.0
version: 5.0.0
packages:
host@5.0.0:
resolution: {integrity: sha512-...}
plugin@2.1.0:
resolution: {integrity: sha512-...}
peerDependencies:
host: '>=4'
util@1.0.0:
resolution: {integrity: sha512-...}
snapshots:
host@5.0.0: {}
plugin@2.1.0(host@5.0.0):
dependencies:
host: 5.0.0
util: 1.0.0
util@1.0.0: {}
Top-level keys#
The project document can contain the following keys.
| Key | Value |
|---|---|
lockfileVersion |
The format version, a string such as '9.0'. Current lockfiles in this format use '9.0', including those with named registry keys. pnpm also reads older '12.0' lockfiles. |
settings |
The settings the lockfile was resolved with. See settings. |
catalogs |
The resolved catalog entries. See catalogs. |
overrides |
The overrides in effect, in the order they are declared. |
packageExtensionsChecksum |
A hash of the packageExtensions in effect. |
pnpmfileChecksum |
A hash of the pnpmfile, when it defines hooks. |
untrackedPnpmfileReadPackageHook |
Whether a hook source excluded from pnpmfileChecksum provides a readPackage hook. Omitted when there is no such source. |
ignoredOptionalDependencies |
The ignoredOptionalDependencies in effect. |
patchedDependencies |
Each patched dependency selector mapped to the SHA-256 hex digest of its patch file. |
importers |
See importers. |
packages |
See packages. |
snapshots |
See snapshots. |
time |
The publish time of each direct dependency, as <name>@<version>: <ISO 8601 date>. Written when resolutionMode is time-based. |
pnpm compares the recorded settings, catalogs, overrides, checksums,
ignoredOptionalDependencies, and patchedDependencies with the current
configuration. If one differs, the lockfile is out of date, and
pnpm install --frozen-lockfile fails.
Loading and saving an existing project document preserves unrecognized top-level keys. Fresh resolution can omit these keys. Readers can look up keys by name regardless of their order.
settings#
| Key | Written |
|---|---|
autoInstallPeers |
Always. The value of autoInstallPeers. |
excludeLinksFromLockfile |
Always. The value of excludeLinksFromLockfile. |
dedupePeers |
As true, when dedupePeers is on. |
addMissingPeerTypes |
As true, when addMissingPeerTypes is on. |
projectScopedOptionalPeers |
As true, when projectScopedOptionalPeers takes effect. |
injectWorkspacePackages |
As true, when injectWorkspacePackages is on. |
peersSuffixMaxLength |
When peersSuffixMaxLength is not the default. |
integrityTarget |
As tar, when lockfile.integrityTarget is tar. |
autoDedupe, dedupeInjectedDeps, dedupePeerDependents, linkWorkspacePackages |
When lockfile.includeResolutionSettings is on. |
catalogs#
catalogs:
default:
example-even:
specifier: ^1.0.0
version: 1.0.0
The keys are the catalog name (default for the default catalog) and then the
dependency name. specifier is the range in the catalog. version is what it
resolved to.
importers#
The keys are project directories, relative to the directory that holds the
lockfile, with / as the separator. The workspace root is ..
importers:
.:
dependencies:
my-example-utils:
specifier: npm:example-utils@4.17.21
version: example-utils@4.17.21
devDependencies:
example-odd:
specifier: 3.0.1
version: 3.0.1(patch_hash=580339f3...)
optionalDependencies:
example-file-watcher:
specifier: 2.3.3
version: 2.3.3
packages/app:
dependencies:
lib:
specifier: workspace:*
version: link:../lib
| Key | Value |
|---|---|
dependencies, devDependencies, optionalDependencies |
The project's direct dependencies of that type. Each key is the name the dependency is installed under in the project's node_modules. |
dependenciesMeta |
The project's dependenciesMeta, as declared. |
publishDirectory |
The project's publishConfig.directory. |
linkDirectory |
false when workspace links to this project ignore publishDirectory. |
Each dependency has two fields:
specifier: the value from the project'spackage.json.version: what it resolved to, in one of the forms below.
version form |
Example | Meaning |
|---|---|---|
| Version, with optional suffixes | 2.1.0(host@5.0.0) |
The snapshot key is <dependency name>@<version>. |
<name>@<version> |
example-utils@4.17.21 |
An aliased dependency. The snapshot key is the value itself. |
link:<path> |
link:../lib |
A symlink to a directory, relative to the project directory. There is no snapshot. |
file:<path>, with optional suffixes |
file:packages/lib(host@5.0.0) |
An injected workspace project, a local directory, or a local tarball. The path is relative to the lockfile's directory. The snapshot key is <dependency name>@<version>. |
| URL | https://codeload.github.com/... |
A package from a URL, such as a git host archive. The snapshot key is <dependency name>@<version>. |
A value is an alias when a package name comes before the version: it starts
with @, or it contains an @ before any ( or :.
Boot document importers#
The boot document has a single importer, ., with its own
dependency groups.
| Key | Value |
|---|---|
configDependencies |
Resolved config dependencies. This map can be empty. |
packageManagerDependencies |
Resolved package manager dependencies from packageManager or devEngines.packageManager. Omitted when absent. |
Each group maps a dependency name to a {specifier, version} entry. The
specifier records the requested version or range. The version records
the selected version. These dependencies use the boot document's own
packages and snapshots maps.
Package keys#
The keys of snapshots are full package keys:
<name>@<version>[(patch_hash=<hash>)][(<peer>)...]
| Part | Content |
|---|---|
<name> |
The package name from its manifest. |
<version> |
One of: a semver version; <registry>:<version> for a package from a named registry; runtime:<version> for a runtime; file:<path> for a local directory or tarball; or the URL of a non-registry package. |
(patch_hash=<hash>) |
Present when the package is patched. <hash> is the hex digest recorded in patchedDependencies. |
(<peer>) |
One group for each peer dependency that the package or its dependencies resolved from outside the package. See peer suffixes. |
The keys of packages are the same keys without the patch hash and the peer
suffixes. To find the packages entry of a snapshot, strip the trailing
parenthesized groups. Older lockfiles can also have a
platform variant segment.
snapshots: example-linter@9.39.5(example-color@7.2.0)
packages: example-linter@9.39.5
snapshots: example-odd@3.0.1(patch_hash=580339f3...)
packages: example-odd@3.0.1
Platform variants in older lockfiles#
Older lockfiles can contain keys such as
example-image@1.0.0/variants/linux-x64(example-host@2.0.0). The
/variants/<tag> segment appears after the registry version and before any
parenthesized suffixes. The metadata is under example-image@1.0.0. Packages
using file: paths or URLs can contain /variants/ as part of the path.
For those lockfiles, pnpm used the target platform to choose a variant from
the package's resolution.variants. If that variant had its own snapshot,
pnpm used its dependency maps in place of the base snapshot's maps.
A graph reader covering all targets needs to visit the variant snapshots
as well.
Peer suffixes#
A peer group normally contains the provider's full package key, including its own suffixes. Groups can therefore nest.
@example/lint-plugin@8.0.0(example-compiler@5.6.3)(example-linter@9.39.5(example-color@7.2.0))
With dedupePeers, or when
breaking a peer cycle, pnpm can use only the provider's name and version.
For a linked provider, the group contains the dependency name and an encoded
link path. For example, example-host linked as link:packages/host appears
as (example-host@packages+host).
pnpm sorts the group contents and joins them with )(. This body includes any
nested parentheses and excludes the outermost pair. If its UTF-8 byte length
exceeds peersSuffixMaxLength, pnpm
replaces the body with the first 32 hex characters of its SHA-256 digest.
pnpm wraps the resulting body in parentheses. Use the dependency maps to
follow resolved edges, including when a peer group is shortened or hashed.
A package that has no peer dependencies, and whose dependencies resolve none from outside it, has no suffix. The same package version has one snapshot for each distinct set of peers it was resolved with.
packages#
Facts about a package version that are the same for every snapshot of it.
packages:
example-logger@4.4.3:
resolution: {integrity: sha512-...}
engines: {node: '>=6.0'}
peerDependencies:
example-color: '*'
peerDependenciesMeta:
example-color:
optional: true
example-file-watcher@2.3.3:
resolution: {integrity: sha512-...}
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
os: [darwin]
| Key | Value |
|---|---|
resolution |
Where to fetch the package. See resolution. |
version |
The version from the manifest. Written when the key's <version> is a URL, a file: path, or a runtime: version. Not written for a directory. |
engines, cpu, os, libc |
Copied from the manifest. pnpm skips an optional package whose cpu, os, or libc does not match the current system. |
deprecated |
The registry's deprecation message. |
hasBin |
true when the package declares executables. |
bundledDependencies |
The package's bundled dependencies: a list of names, or true. |
peerDependencies |
The package's peer dependencies and their ranges. |
peerDependenciesMeta |
Which peer dependencies are optional. An optional peer is listed in both peerDependencies and peerDependenciesMeta. |
resolution#
| Form | Fields | Used for |
|---|---|---|
| Registry | integrity, optional revision |
A package from a registry. The tarball URL is derived from the registry and the package key. |
| Tarball | tarball, optional integrity, gitHosted, path, revision |
A tarball at a URL or a local path. gitHosted: true marks a git host archive. path is a subdirectory inside the tarball. |
type: directory |
directory |
A local directory, relative to the lockfile's directory. |
type: git |
repo, commit, optional path |
A git repository cloned at commit. |
type: binary |
url, integrity, bin, archive, optional prefix |
A binary archive, such as a runtime. |
type: variations |
variants |
Platform-specific resolutions for a runtime or a registry package from an older lockfile. Each variant has a resolution and the targets it applies to. |
A type value other than those above is a custom resolution, defined by a
resolver plugin. Its other fields belong to that resolver.
For revision, see Resolutions that carry a revision.
For what integrity pins, see Which hash integrity pins.
snapshots#
A snapshot records a package's resolved dependencies in a particular peer
context. For example, pnpm install --lockfile-only writes snapshots without
installing packages. When the isolated linker
installs a package, it uses its snapshot to link the package's dependencies
in the virtual store.
snapshots:
example-logger@4.4.3(example-color@7.2.0):
dependencies:
example-duration: 2.1.3
optionalDependencies:
example-color: 7.2.0
example-file-watcher@2.3.3:
optional: true
example-utils@4.17.21: {}
| Key | Value |
|---|---|
dependencies |
Packages linked next to this one. See below. |
optionalDependencies |
The same, for edges that may fail to install. See below. |
transitivePeerDependencies |
See transitivePeerDependencies. |
optional |
true when every path from a project to this snapshot goes through an optional dependency. pnpm then skips the package if it cannot be installed or built. |
A snapshot with none of these is written as {}.
Dependencies of a snapshot#
dependencies and optionalDependencies map the name a package is linked
under to a reference. They list both the package's own dependencies and the
providers of its resolved peer dependencies:
| Edge | Listed under |
|---|---|
An entry of the manifest's dependencies |
dependencies |
An entry of the manifest's optionalDependencies |
optionalDependencies |
| A resolved required peer dependency | dependencies |
| A resolved optional peer dependency | optionalDependencies |
A peer dependency that is not resolved is not listed. The list of a
snapshot's peers is in its packages entry.
A reference has one of these forms:
| Form | Example | Snapshot key |
|---|---|---|
| Version, with optional suffixes | example-duration: 2.1.3 |
<name>@<version>, here example-duration@2.1.3 |
<name>@<version> |
example-width-cjs: example-width@4.2.3 |
The value itself. The dependency is an alias. |
link:<path> |
c: link:packages/c |
None. A symlink to a directory relative to the lockfile's directory. |
link:<root>/<path> |
types: link:<root>/typings/css |
None. A symlink to a directory inside this package. |
The alias rule is the same as for importers.
transitivePeerDependencies#
The names of peer dependencies that packages below this one declare, which are not resolved inside this snapshot's subtree and are not this package's own peer dependencies. Each name is one of:
- Resolved from outside this package. The provider then also appears in this snapshot's peer suffix.
- Not resolved anywhere.
container@3.2.2(buffer-impl@3.7.1):
dependencies:
fs-impl: 4.8.4(buffer-impl@3.7.1)
transitivePeerDependencies:
- abort-impl
- buffer-impl
Here fs-impl declares the optional peers buffer-impl and abort-impl.
buffer-impl is resolved from outside container, so it is in container's
suffix. abort-impl is not installed, so it is listed but not in the suffix.
Fields of older lockfiles#
Lockfiles written by earlier pnpm versions can carry id and patched: true
in a snapshot. pnpm reads them and does not write them.
How a peer dependency ends up in the lockfile#
A worked example. container depends on fs-impl and url-impl. fs-impl
declares buffer-impl as an optional peer dependency, and url-impl depends
on buffer-impl. This example uses workspace-wide optional peer selection
with dedupePeerDependents: true and projectScopedOptionalPeers: false.
snapshots:
container@3.2.2(buffer-impl@3.7.1):
dependencies:
fs-impl: 4.8.4(buffer-impl@3.7.1)
url-impl: 2.5.6
transitivePeerDependencies:
- buffer-impl
fs-impl@4.8.4(buffer-impl@3.7.1):
optionalDependencies:
buffer-impl: 3.7.1
url-impl@2.5.6:
dependencies:
buffer-impl: 3.7.1
buffer-impl@3.7.1: {}
buffer-implis not a dependency ofcontaineror of any of its ancestors. It is installed elsewhere in the graph, as a dependency ofurl-impl. pnpm resolves an optional peer dependency to such a version.fs-implgets the suffix(buffer-impl@3.7.1), andbuffer-implis listed under itsoptionalDependencies, because the peer is optional.containerdoes not providebuffer-implitself, so the suffix carries up tocontainer, andbuffer-implis listed in itstransitivePeerDependencies.url-implhas a regular dependency onbuffer-impl, so it has no suffix.
If url-impl is updated to a version that drops buffer-impl and pnpm finds
no provider for the optional peer, the keys of fs-impl and container lose
their suffix. An update targeting url-impl can leave buffer-impl@3.7.1
pinned in the lockfile. If pnpm still selects that pin, the suffix remains.
Invariants#
A lockfile written by pnpm satisfies these:
- Every
versioninimportersand every reference insnapshotsthat is not alink:resolves to a key ofsnapshots. - Every snapshot has a
packagesentry. Strip its parenthesized suffixes and any legacy platform variant segment to find the metadata key. - The maps under
importers,packages,snapshots, and their dependency maps are sorted by key.overrideskeeps its declared order.