---
title: "Dependency Locks: a package format extension · semver.xyz"
description: "Dependency Locks is a package format specification for attaching a resolved transitive subgraph to a source-qualified package identity. Reference implementation planned in vlt."
url: "https://semver.xyz/extensions/dependency-locks/"
lang: "en"
---

Package format specification

# Pin a dependency's subgraph ahead of time.

A _Dependency Lock_ captures one dependency's resolved subgraph as a portable, shareable value. Resolve it once; any aware tool pins that slice of the graph to it.

specifier grammar

```
npm:express@5.2.1+lock.163pGWiielRlPY5wPsWb7DtsYkTwvpFTO8OPltrZZ7s6pBrPgoOZ…
```

`npm:express@5.2.1` is the package you already install. `+lock.…` is the only new part: a pinned, shareable copy of the resolved subgraph, computed ahead of time.

[Read the format](https://www.semver.xyz/extensions/dependency-locks#format) [Open the spec](https://github.com/vltpkg/semantic-versions/blob/main/extensions/dependency-locks/dependency-locks.md)

A specification from vlt. Support is planned in the vlt client and hasn't shipped yet, so this is not a claim of package-manager support today.

Why this exists

## Maintainers still want to pin what they ship.

`npm-shrinkwrap.json` was the one widely-deployed way to _publish_ a locked dependency tree with a package, and npm is removing it in its next major (**v12**). The demand never went away. When a tool like the Pi coding agent ships as a global `npm install`, its authors want to guarantee the exact transitive graph they tested, and shrinkwrap was how they did it. People are now asking for a `--locked`-style install, declarative builds like Nix leaned on shrinkwrap, and CLI authors still ship generated shrinkwraps to harden their supply chain.

But shrinkwrap earned its bad reputation: in a published package it is _hostile to consumers_: it freezes the whole tree, blocks deduping, and stops people from patching through security fixes, while quietly bypassing normal install rules. A maintainer wants to say _“append this string; we've tested this subgraph”_ and have it respected, without taking the final say away from the person installing. A Dependency Lock is that: a tested resolution the maintainer distributes, applied as one layer the consumer still overrides.

An input, not a mandate

Shrinkwrap froze the consumer's tree and blocked security updates. A lock is a seed: the consumer's tool can honor, override, re-resolve, or reject it, and package-manager config stays authoritative.

Integrity isn't bypassed

Shrinkwrap could pull unsigned code from any host and slip past SCA tools. A lock can pin each artifact's integrity as tamper-evidence, and your package manager still independently verifies every artifact through its normal metadata and fetch checks.

Scoped, so dedupe still works

Shrinkwrap pinned the entire project and prevented deduping. A lock pins one dependency's subgraph, so the installer can still flatten and dedupe across the rest of the tree.

Degrades to the bare version

A stale, hand-maintained shrinkwrap quietly trapped you on old, vulnerable versions. A stale, malformed, or rejected lock falls back to the plain version and re-resolves.

Portable, not a sidecar

Shrinkwrap was an npm-specific file dropped next to the package. A lock rides inside the dependency value across tools and registries, and node identity carries its source so the same `name@version` from different registries stays distinct.

Canonical and auditable

A large JSON tree is hard to review and diff. A lock is a deterministic binary graph with a single digest for equality, caching, and tamper-evidence.

## This is a distributable resolution seed.

Dependency Locks define how maintainers can publish not just a package version, but the resolved dependency subgraph rooted at that version. Aware tools can use it before generating their native lockfile.

## The graph is the payload.

That subgraph is just a plain graph (resolved package instances and typed edges) narrowed to one rooted dependency. It fixes that dependency's transitive choices, not the whole project graph, install layout, or config.

01

### Nothing extra to commit

The resolved subgraph travels inside the dependency value itself, so there is no separate lockfile to generate, share, or keep in sync.

02

### Same graph, same bytes

An identical subgraph always encodes to the same bytes and the same `SHA-256`, so two locks are equal by comparing one hash.

03

### Scoped to one dependency

It pins a single dependency's transitive closure rather than the whole project, so each dependency can carry its own pinned subgraph.

04

### Works with today's tools

The marker rides in standard SemVer build metadata, so a tool that doesn't understand it still installs the plain `npm:express@5.2.1`.

05

### The tool stays in charge

A consumer can honor, ignore, override, remap sources, or reject the lock under its own configuration; it is an input, not a mandate.

06

### Integrity rides along

A lock can carry each artifact's integrity hash as advisory tamper-evidence; it never replaces verification. Your package manager still independently checks every artifact it fetches.

Resolution semantics

## A lock pins a dependency's subgraph before lockfile generation.

If a package manager supports Dependency Locks and chooses to honor one, the lock supplies the resolved dependency definitions for that rooted subtree before the consumer's native lockfile is generated. It is then still subject to user-level configuration, policy, registries, overrides, and the package manager's own installation model.

Resolution cascades, like CSS: the layer closest to the consumer wins.

1. 1

   **Maintainer's lock** “Append this string; we've tested this subgraph.” A distributed, pinned resolution.
2. 2

   **Package manager** vlt is where support is planned first. Until it ships, every tool is lock-unaware and installs the bare version.
3. 3

   **User configuration** Overrides, source remaps, security policy, and install mode have the final say, and can reject it outright.

Scope

Applies to the transitive/subgraph rooted at a specific dependency, not to unrelated siblings in the project graph.

Override point

When honored, supplies resolved dependency targets before user-level configuration is applied.

User policy

Package-manager config remains authoritative: overrides, source remaps, security policy, and install modes can still change or reject the result.

Integrity

A lock may carry artifact integrity as advisory tamper-evidence; it doesn't replace verification. The package manager still independently enforces integrity through its normal lockfile and fetch pipeline.

The format

## A small nodes-and-edges graph, scoped to one subtree.

The payload is its own compact graph format: just resolved `nodes` and typed `edges` for one rooted subtree, no config. It's modeled on [vlt](https://www.vlt.io/)'s lockfile graph and maps cleanly to and from it, but it's deliberately generic. Each node is one origin-qualified id like `npm:react@1.2.3`, with no tool-specific encoding, so any package manager can implement it. The version stays ordinary SemVer; `npm:` just supplies the origin.

1

#### Capture the subgraph

Resolve one rooted subtree into a plain graph of `nodes` and typed `edges`, plus optional per-node integrity and platform conditions, with no config. It maps cleanly onto vlt's graph.

→

2

#### Encode canonically

Serialize that graph to a deterministic binary blob: a columnar layout with structural versions, varints, and delta-encoded edges. Not JSON.

→

3

#### Compress & frame

Brotli when it pays off (tiny graphs ship uncompressed), then prepend a one-byte frame that identifies the format and codec.

→

4

#### Armor as Base62

Base62 keeps the version legal SemVer. That helps with transport, but does not mean the package manager supports the lock semantics.

`npm:name@version`+`canonical graph`→`Brotli`→`frame byte`→`Base62`→`npm:name@version+lock.<payload>`

Decoded payload

## Decoded, it's a small nodes-and-edges graph.

The `+lock.<payload>` blob is compact binary built for transport. Decode it and you get a plain graph: each `node` is an origin-qualified id like `npm:lightningcss@1.32.0`, optionally carrying its artifact integrity as [Package Integrity](https://www.semver.xyz/extensions/integrity.md) build metadata (`+sha512.…`) and platform conditions (`[os=… cpu=…]`); each `edge` is just `from -> to = type` (`prod`, `optional`, `peer`). Nothing tool-specific; it maps one-to-one onto vlt's lockfile graph, but anyone can read or emit it.

Note that a node id is _exactly_ a version written in the two extensions beneath this one: a [Build Variant](https://www.semver.xyz/extensions/variants.md)'s coordinates (where the node is target-specific) followed by a Package Integrity digest, in that order. There is no lock-specific spelling of a package identity to learn — a decoded node is just a source-qualified version you could paste into a manifest on its own.

decoded · npm:lightningcss@1.32.0 subtree

```
format = 2
root = 0

[nodes]
0 = npm:lightningcss@1.32.0+sha512.357601ce29cd… [engines=>=12]
1 = npm:detect-libc@2.1.2+sha512.06d8f604e38e… [engines=>=8]
2 = npm:lightningcss-darwin-arm64@1.32.0+sha512.473786f49bb9… [os=darwin cpu=arm64]
3 = npm:lightningcss-linux-x64-gnu@1.32.0+sha512.57b42be76221… [os=linux cpu=x64 libc=glibc]

[edges]
0 -> 1 = prod
0 -> 2 = optional
0 -> 3 = optional
```

A deliberately small, generic shape: origin-qualified node ids, an optional `+<algorithm>.<digest>` integrity build and `[platform]` conditions, and `from -> to = type` edges, nothing tool-specific. Where a node is target-specific its [variant](https://www.semver.xyz/extensions/variants.md) coordinates precede the digest, exactly as in a standalone version — `npm:sharp@0.33.0+linux.x64.musl.sha512.a91c…`. Integrity is advisory tamper-evidence; your package manager still verifies every artifact. The graph translates one-to-one to vlt's lockfile graph (and back), but is simple enough for any package manager to implement. The lock digest is taken over the canonical encoding of exactly this graph, so the same subtree always yields the same lock.

Try it

## Generate a lock in your browser.

Type any public npm package. This resolves its registry subgraph live against `registry.npmjs.org`, then runs the real pipeline (canonical binary → SHA-256 digest → Brotli (or stored) → frame byte → Base62) and hands back a copy-pasteable `+lock.<payload>`. No server: it all runs here. Non-registry dependencies (git, `file:`, `workspace:`) are skipped and listed below.

- npm package name and optional version range

Embed artifact integrity (sha512 per node) Tamper-evidence, but hashes don't compress, so toggle off for a smaller payload.

Manifest example

## A dependency value can carry the locked subgraph.

package.json

```
{
  "name": "my-app",
  "dependencies": {
    "express": "npm:express@5.2.1+lock.<payload>",
    "lodash":  "npm:lodash@4.18.1+lock.<payload>"
  }
}
```

An aware package manager running `prefer` can decode, validate, and absorb each closure into its native lockfile. A lock-unaware tool simply installs `npm:express@5.2.1` / `npm:lodash@4.18.1`.

Support status

## Planned in vlt first. Portable by specification.

Dependency Locks are a new idea, and no mainstream package manager honors them yet. npm, pnpm, yarn and bun will not decode or act on the lock. The only compatibility we claim is at the transport layer: an exact SemVer version can carry the lock as build metadata without breaking tools that already parse versions.

vlt

Reference implementation, planned. Support hasn't shipped yet; once it lands, vlt will decode, validate, and use the locked subgraph during resolution.

Other package managers

May adopt the format later. Until one does, it stays lock-unaware, not lock-compatible: it installs the plain version and ignores the lock.

Existing SemVer parsers

Mostly relevant to transport. Accepting `+lock.<payload>` is not the same as honoring Dependency Locks.

Size ceiling

`node-semver` caps a version string at **256 characters**, leaving about 245 for the payload. Measured, that holds roughly ten nodes without integrity, or two or three with `sha512`. Past the cap npm silently reclassifies the specifier as a range and drops the lock from resolution, so an oversized inline lock goes quietly inert rather than erroring.

Ecosystem scope

Riding inside the version is an **npm-ecosystem mechanism**. Python cannot use it at any length: PEP 440 treats the `+…` slot as a _local version identifier_, lowercases it (destroying a Base62 payload), requires resolvers to ignore it when matching specifiers, and PyPI refuses to accept it at all. There the graph model still applies — the sidecar does not.

Sidecar path

Carries the identical canonical payload outside the version string, with no length ceiling. For package managers that reject build metadata, for ecosystems where the inline form is unavailable, and for any closure past the cap above, which in practice means most real packages.

Security model

## Fail closed at the artifact boundary.

### Tamper-evident

Each node can pin its artifact integrity, and root-match blocks pasting a foreign closure under another name. The host package manager's integrity pipeline still independently catches substituted artifacts.

### Bounded decoding

Canonical parsing plus size, node, edge, ratio, and fetch fan-out caps defend against malicious payloads and amplification.

### The right boundary

Stale, malformed, or future-format locks degrade to the still-valid bare version. Artifact substitution still fails the normal integrity boundary.
