A lockfile records the exact versions and integrity data of your dependencies, so installs are repeatable and a new upstream release cannot slip in unnoticed. It does not check that the recorded version is safe, and it does not stop an attack that happens before the version was locked.
Definition
A lockfile, such as package-lock.json, records the resolved dependency tree. The npm ci command installs from it, requires that it exists, and exits with an error if it does not match package.json, instead of updating it. Pip has a related mechanism: the require hashes option checks each requirement against a hash for repeatable installs.
What it covers
| Scenario | Does a lockfile help? |
|---|---|
| A maintainer publishes a bad new version after you locked | Yes, if installs use the lockfile and you have not updated |
| A package is swapped on the registry under the same version | Often, when integrity hashes are recorded and checked |
| Dependency confusion when adding a new internal name | Not on first resolution |
| You update to a bad version | No, it records the bad version |
| A malicious build of a vendor product | No, it is outside the package manager |
| A bad version already in the lockfile | No |
Using it well
- Commit it. For applications, commit the lockfile so everyone and every build gets the same tree.
- Install from it in CI. Use the lockfile-strict install command, not the one that updates it.
- Review lockfile changes. A lockfile diff in a pull request is where a surprise dependency shows up. GitHub's dependency review shows added, removed and updated dependencies on pull requests that change manifests or lock files, including indirect ones.
- Treat updates as events. Each update is a decision, with a short delay and a look at what changed.
What it cannot do
It cannot judge intent. If the version you lock is malicious, the lockfile makes your install reproducibly malicious. That is why a lockfile pairs with monitoring and an inventory that can flag a version after the fact.
For buyers
When you evaluate a scanner, check that it reads lockfiles to get exact transitive versions, since manifest ranges alone do not tell you what actually shipped.
Try it yourself
Open the demo and look at how exact component versions drive the findings you see.
Click through it at your own pace, or open it full screen.
Where Safeguard fits
Safeguard offers SBOM and dependency scanning that reads your project's dependency data, and gates that can run on pull requests. The free scan is a quick way to see a lockfile turned into an inventory.
Quick check
Should libraries commit lockfiles?
Practice differs by ecosystem. Applications should commit them. Check your ecosystem's guidance for libraries.
Does npm install behave like npm ci?
No. npm install can update the lockfile, while npm ci errors on a mismatch and never writes to it.
Sources
Last reviewed: 19 October 2026.
