Home / Knowledge hub / Lockfile
Knowledge hub
Lockfile
A file pinning exact dependency versions so builds are repeatable and checkable.
What it means
A lockfile is a file generated by a package manager that records the exact version of every dependency installed, including dependencies of dependencies. Examples are package-lock.json for npm, yarn.lock, Pipfile.lock and Cargo.lock. Many also store a checksum for each package.
Your manifest, such as package.json, states a range, for example any 4.x version. The lockfile freezes the answer that was chosen on a given day. Anyone who installs from it gets the same versions, rather than whatever is newest when they run the install.
Why it matters
Without a lockfile, two builds a week apart can contain different code, and a compromised new release can reach production without anyone approving it. With one, a change in dependencies appears as a change in a file that a person can review before it merges.
The checksums let an install detect a package that has been altered since it was approved. A lockfile also gives composition analysis and an SBOM an accurate list to work from, which makes dependency vulnerabilities much easier to trace when a new advisory is published.
How it shows up
You meet it in every modern project, committed beside the manifest. Repeated mistakes are not committing it, deleting it to fix a conflict, installing with a command that ignores it, and approving a huge lockfile diff without reading it. Updates then happen by accident.
In npm, the npm ci command installs exactly what the lockfile says and fails if it disagrees with the manifest, which makes it the right choice for builds. Commit the file, review its changes, and update on purpose through a bot or scheduled task. A lockfile pins versions; it does not make them safe.
Questions people ask
Lockfile, answered
Should a lockfile be committed to version control?
For applications, yes. It is what makes builds repeatable and reviewable. For libraries, practice varies by ecosystem, since consumers resolve their own versions, so follow your package manager's own guidance for libraries.
What is the difference between npm install and npm ci?
npm install may update the lockfile when ranges allow newer versions. npm ci installs exactly what the lockfile says and errors if it does not match package.json. Use npm ci in build pipelines.
Does a lockfile protect against a malicious package?
Only partly. It stops a new malicious release from being pulled in silently, and checksums detect tampering. It does not help if the pinned version is already bad or if you update to one.
Why do lockfile diffs matter in review?
A diff shows which packages and versions are changing. An unexpected new package, a changed registry address or a change in an unrelated dependency deserves a question before it is merged.
Is a lockfile an SBOM?
No. A lockfile is a build input for a package manager. An SBOM is a standard-format inventory of components that can be shared. A lockfile can be used to generate one.
Sources
Where this comes from
Related
Terms that sit next to this one
Package pinning
Fixing a dependency to one exact version rather than accepting any newer release.
Dependency confusion
Tricking a build into fetching a public package that shares a private package's name.
SBOM
A list of every component your application includes, with versions.
Transitive dependency
A library pulled in by another library you chose, which you still ship.
Reproducible builds
Builds that produce identical output every time, so tampering shows up.
Does your build get what you approved?
Pinned dependencies make a build repeatable, and a CI/CD gate can stop a build when a finding appears. We test your running app and report only what we proved. Ask us to run it on one of your applications.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.