Dependency lock file

Also known as: package-lock

On this page 7

A dependency lock file is a machine-generated file that records the exact resolved version, source location and integrity checksum of every direct and transitive dependency a software project installs. In the field of Installation & packages, it turns a flexible list of version ranges into a reproducible dependency tree, so that a developer laptop, a continuous integration server and a production image all receive identical code.

Common examples include package-lock.json for npm, yarn.lock, pnpm-lock.yaml, Cargo.lock, poetry.lock, Gemfile.lock, composer.lock and go.sum. The npm variant is so widespread that many developers simply call the concept a package-lock.

How a dependency lock file is produced and used

A lock file is the output of dependency resolution and the input of every later installation. The project manifest, such as package.json or Cargo.toml, declares version constraints like ^4.17.0; the package manager then searches the registry, picks concrete versions that satisfy all constraints, and writes the result to the lock file.

On the next install, the package manager reads the lock file first and skips resolution for every entry that still matches the manifest. Because transitive packages are pinned as well, a new upstream release published overnight cannot silently enter the build. This is the core guarantee: same inputs, same tree.

The table below shows what a typical lock file entry stores and why each field matters.

FieldExample contentPurpose
Package namelodashIdentifies the dependency
Resolved version4.17.21Fixes the exact release installed
Source or registry URLRegistry tarball addressShows where the artifact came from
Integrity hashSHA-512 or SHA-256 digestDetects tampered or corrupted downloads
Dependency edgesList of required child packagesReconstructs the full tree without resolving
Metadata flagsDev-only, optional, platformControls what is installed in each environment
Typical fields in a lock file entry

Lock file formats across package ecosystems

Every major ecosystem has its own lock file, and the formats differ in syntax, scope and strictness. Some record a single resolved tree; others, like Go, store only checksums and rely on a deterministic algorithm called minimal version selection to rebuild the tree.

The following comparison lists the most common formats and their notable behavior.

EcosystemLock fileFormatNotable behavior
npmpackage-lock.jsonJSONRecords the full nested tree and integrity hashes
Yarnyarn.lockCustom text or YAMLDeduplicates ranges onto shared versions
pnpmpnpm-lock.yamlYAMLPairs with a content-addressed store
Cargo (Rust)Cargo.lockTOMLCommitted for binaries, optional for libraries
Poetry (Python)poetry.lockTOMLStores hashes for every distribution file
Bundler (Ruby)Gemfile.lockCustom textLists platforms and the Bundler version
Go modulesgo.sumPlain textChecksums only; versions live in go.mod
Lock files in widely used package managers

Despite these differences, the operational rules are similar: the file is generated by the tool, never edited by hand, and kept in version control alongside the manifest.

Lock files compared with version pinning and vendoring

A lock file is one of several ways to control dependency drift, and it is often confused with neighboring techniques. Version pinning writes exact versions directly into the manifest, but it usually covers only direct dependencies, leaving transitive packages free to change. Vendoring copies the dependency source code into the repository, which removes reliance on the registry at the cost of a much larger codebase.

The table summarizes how these approaches differ in coverage and maintenance effort.

ApproachCovers transitive packagesMaintenance effortMain drawback
Version ranges onlyNoLowBuilds change without any code change
Pinning in the manifestUsually noMediumManual updates and hidden transitive drift
Dependency lock fileYesLow with toolingMerge conflicts and review noise
VendoringYesHighLarge repository and manual patching
Container image digestYes, including system librariesMediumLocks the whole runtime, not just packages
Approaches to reproducible dependencies

In practice these techniques are complementary rather than exclusive. A team may use version ranges in the manifest for flexibility, a lock file for reproducibility, and an immutable container digest for deployment.

Working with lock files in development and CI

Correct lock file handling depends on using the right install command in each context. During development, an ordinary install may update the lock file when the manifest changes. In automated pipelines, a frozen or clean install such as npm ci, yarn install --immutable, pnpm install --frozen-lockfile or cargo build --locked must fail if the lock file and manifest disagree, instead of rewriting the file.

The decision table below covers the situations practitioners meet most often.

SituationRecommended actionReason
Application or serviceCommit the lock fileGuarantees identical deployments
Published libraryCommit for CI, not shipped to usersConsumers resolve their own tree
CI or release buildUse a frozen install commandFails fast on unreviewed changes
Security advisoryUpdate the affected package and regenerateRecords the patched version explicitly
Merge conflict in lock fileRerun the package manager to regenerateHand merging breaks hashes and edges
Recommended lock file practice by situation

Automated update bots open pull requests that change the manifest and lock file together, which keeps updates small, reviewable and testable. Reviewers should look at the resolved versions and new transitive packages, not only at the manifest diff.

Limitations and common mistakes

A lock file guarantees which package versions are installed, not that the resulting software behaves identically everywhere. Native extensions compiled at install time, platform-specific optional packages and different interpreter versions can still produce environment-dependent results.

  • Deleting the lock file to fix an error discards the known-good tree and may pull in dozens of untested upgrades at once.
  • Ignoring the lock file in version control makes every clone resolve a different tree, which defeats its purpose.
  • Mixing package managers, for example running npm in a Yarn project, creates competing lock files and inconsistent installs.
  • Treating the lock file as a security control is a misconception: it freezes vulnerable versions just as firmly as safe ones, so regular audits remain necessary.
  • Stale lock files accumulate technical debt; long gaps between updates make each eventual upgrade larger and riskier.

Integrity hashes do protect against tampered downloads and registry substitution, but they cannot detect a malicious release that was published legitimately and then locked. Supply chain defenses therefore combine lock files with vulnerability scanning, provenance checks and careful review of new packages.

In simple terms

Modern programs are built from hundreds of small pieces written by other people. The project usually says something like any recent version of a piece is fine. That flexibility is convenient, but it means two people installing the same project on different days can end up with slightly different pieces.

A dependency lock file is like a detailed shopping receipt. Instead of saying buy some flour, it says this exact brand, this exact batch, from this exact shelf, with a seal you can check. Anyone who follows the receipt gets exactly the same ingredients, so the result comes out the same every time.

A practical example

A team of six developers maintains a Node.js web service with 40 direct dependencies, which expand to roughly 900 packages once transitive dependencies are counted. One Monday, the nightly build fails although nobody changed the code. Investigation shows that a small date-formatting package three levels deep released a new minor version over the weekend that changed its output format.

The team had excluded package-lock.json from the repository. They restore it, regenerate it from the last successful build, commit it, and switch the pipeline from npm install to npm ci. From then on, upgrades arrive only through weekly automated pull requests that run the full test suite. Over the following quarter, the team records no unexplained build failures, and every production deployment can be traced to one reviewed lock file revision.