Lockfile
A lockfile pins the exact versions and integrity hashes of every dependency, making installs reproducible across machines and time.
Definition
A lockfile records the fully resolved dependency tree — every package, its exact version, its own dependencies, and usually a content hash — produced from a looser version declaration such as a semver range. Committing it lets installs reproduce the same tree everywhere, protects against a newly published malicious or breaking version, and lets a tool verify package integrity. It converts a floating specification into a fixed, auditable set of artefacts.
Context and scope
Standard practice in npm, pnpm, yarn, Cargo, Go, and others, and a prerequisite for reproducible builds and supply-chain review.
Common misconceptions
- A lockfile guarantees security — it freezes versions and integrity hashes, but a pinned version can still be vulnerable, so it must be reviewed and updated
- It makes dependencies immutable forever — update commands deliberately move the pins; the point is control, not stagnation
- It is optional for applications — it is essential precisely for applications, where every install must match production
Anti-patterns
- Gitignoring the lockfile, so every machine and CI run resolves different versions
- Hand-editing a lockfile instead of regenerating it with the package manager
- Letting a lockfile drift for years without dependency updates, accumulating known vulnerabilities
Related concepts
Authoritative source
https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json
What it is
A manifest declares dependencies as ranges — “^1.2.0” — which many concrete versions satisfy. A lockfile is the output of resolving those ranges once: it lists each package at an exact version, with the subgraph it pulls in and a hash of its contents. Installers then follow the lockfile rather than re-resolving, so the same tree is installed on every machine, and the hash lets the installer detect a package whose contents changed.
Why it matters
Without a lockfile, two developers can install different versions on the same day, and CI may install yet another, making “works on my machine” a versioning problem. Worse, a range can silently pull a newly published version that is broken or malicious. Pinning versions and verifying integrity hashes makes installs reproducible and gives the supply chain a fixed set of artefacts to scan and attest.
How to use it well
Commit the lockfile for applications so every environment installs identically, and install from it in CI with deterministic, frozen mode. Update dependencies deliberately and re-review the diff, since a bump also changes transitive packages. Never hand-edit the file; regenerate it with the package manager. Feed it to dependency scanning and, for high-assurance pipelines, to provenance checks, but treat it as a snapshot to maintain rather than a permanent guarantee.