Infra8 min read
Don't underestimate lock files: npm ci, conflicts, security
What package-lock.json, yarn.lock and pnpm-lock.yaml really do, why commit them, npm ci vs npm install, the integrity hash and how to resolve conflicts.

If you use npm, Yarn or pnpm, you've seen a package-lock.json, a yarn.lock or a pnpm-lock.yaml in the project. A lot of people ignore it, delete it when there's a conflict or don't even commit it.
That's a serious mistake, and in this post I show you why with examples I actually ran, not just with theory.
I first published this post on Medium in September 2025, in Portuguese. This is the revised version, with tests, npm ci (which was left out of the original), the right way to resolve conflicts and a correction about what the integrity hash protects and what it doesn't.
TL;DR#
package.jsonaccepts version ranges (^2.0.0means "any 2.x"). The lock file stores the exact version that was installed, for each dependency and for their dependencies.- Without the lock, the same
package.jsoninstalls different versions on different days. In my test, I got2.1.1with the lock and2.1.3without it. - Commit the lock file and never delete it to "fix" a problem.
- In CI, use
npm ci(orpnpm install --frozen-lockfile, oryarn install --immutable). It installs exactly what's in the lock and fails if the lock is out of date. - The integrity hash guarantees the package is the same one that was locked, byte for byte. It doesn't tell you whether the package is safe, but it stops a new version, maybe a malicious one, from slipping in without anyone noticing.
- Conflict in the lock: resolve
package.jsonand runnpm installagain. npm rebuilds the lock on its own. - One project, one package manager. Mixing npm and Yarn creates two locks that disagree.
What the lock file does#
In package.json, you rarely write an exact version. By default, npm install saves a range:
{
"dependencies": {
"ms": "^2.0.0"
}
}^2.0.0 means "any 2.x version from 2.0.0 up". Today that might be 2.1.1. Tomorrow, if a 2.1.4 comes out, it's that one. And this applies to every dependency of your dependencies too.
The lock file solves this: it stores the exact version that was installed, where it came from and a hash of the file. This is the ms entry in the package-lock.json from my test:
"node_modules/ms": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
"integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg..."
}The test: the same package.json, two versions#
I set up a project with ms locked at 2.1.1 and package.json accepting ^2.0.0. Then I installed twice: once with the lock, and once copying only package.json into a new folder.
$ npm ci && node -p "require('ms/package.json').version"
2.1.1
# same package.json, no lock file
$ npm install && node -p "require('ms/package.json').version"
2.1.3This is exactly "works on my machine": whoever installed six months ago has one version, whoever cloned today has another, and the bug only shows up for one of the two. With the lock committed, both install the same thing.
npm install or npm ci?#
Both install dependencies, but with different goals:
npm installrespects the lock as long as it matchespackage.json, but it can update the lock: if you added a package or changed a range, it resolves again and rewrites the file. It's the everyday command, for when you want to change dependencies.npm cideletesnode_modulesand installs exactly what's in the lock. It never changes the lock. Ifpackage.jsonand the lock don't match, it stops with an error:
npm error code EUSAGE
npm error `npm ci` can only install packages when your package.json and package-lock.json
or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install`
before continuing.That error is there to help: someone changed package.json and forgot to commit the lock. Better for CI to break than to ship to production with versions nobody tested.
Rule of thumb: npm install on your machine when you want to change dependencies; npm ci in CI, in Docker and whenever you just want to install what the project already defines.
The other package managers have the equivalent:
| Package manager | Lock file | Install without touching the lock |
|---|---|---|
| npm | package-lock.json | npm ci |
| pnpm | pnpm-lock.yaml | pnpm install --frozen-lockfile |
| Yarn (2 or newer) | yarn.lock | yarn install --immutable |
| Yarn 1 | yarn.lock | yarn install --frozen-lockfile |
In pnpm and modern Yarn, this mode is already the default when they detect they're running in CI.
The integrity hash#
Each package in the lock has an integrity field, a SHA-512 hash of the downloaded file. On install, npm computes the hash of what arrived and compares. To see this in action, I replaced the ms hash in the lock with a fake one:
$ npm ci
npm error code EINTEGRITY
npm error sha512-AAAA...== integrity checksum failed when using sha512:
wanted sha512-AAAA...== but got sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg...npm refused to install. The original version of this post said this hash "prevents malicious libraries from being installed", and that needs an adjustment. The hash guarantees the package is exactly the same one that was locked. If the locked version were already malicious, the hash would match all the same.
The real protection is somewhere else: with the lock and npm ci, a new version doesn't get in without someone asking for it. On September 8, 2025, a week after the original post, a maintainer's account was compromised and malicious versions of widely used packages, like chalk@5.6.1 and debug@4.4.2, stayed on npm for about two hours. A project with a ^ range and no lock, installing in that window, could pull the infected version. A project with the lock pinned to an earlier version and installing with npm ci kept the version it had before.
Good practices#
1. Commit the lock file#
It's part of the project, like package.json. Without it in Git, every person and every build resolves the ranges again and can end up with different versions. The only common exception is if you publish a library to npm: its lock doesn't go along to the project of whoever installs it. Even so, it's worth committing, so your own CI is reproducible.
2. Don't delete the lock to fix a problem#
Deleting the lock and running npm install doesn't "clean" anything: it updates all dependencies at once, even the ones that had nothing to do with the problem. If something broke, you just traded one bug for twenty changes nobody reviewed. Understand the error first. If you need to update a package, update that package.
3. Conflict in the lock: let the package manager resolve it#
Two branches added different dependencies, and the merge hit a conflict in package.json and in the lock. Resolving the lock by hand, line by line, is asking for mistakes. The right way:
- resolve the
package.jsonconflict by hand (it's short and readable); - run
npm install.
npm understands the conflict markers in package-lock.json and rebuilds the file combining both sides (tested on npm 11). In my test, one branch added left-pad and the other is-number. After combining the two in package.json and running npm install, the lock had no conflict markers left and had both packages:
$ git merge feat-a
CONFLICT (content): Merge conflict in package-lock.json
CONFLICT (content): Merge conflict in package.json
# fix package.json by hand, then:
$ npm install
added 1 package, and audited 4 packages in 395msThen check the lock diff before committing. It should only show the packages from the two branches.
4. One project, one package manager#
If the project has package-lock.json, use npm. If it has pnpm-lock.yaml, use pnpm. Running yarn in an npm project creates a yarn.lock that knows nothing about package-lock.json, and the two start disagreeing about versions.
To make this explicit, declare the package manager in package.json. pnpm and Yarn read this field:
{
"packageManager": "pnpm@10.0.0"
}5. Update on purpose#
Want to update? Use the package manager's command, and preferably one package at a time:
npm outdated # what is behind
npm update ms # update within the package.json range
npm install ms@latest # jump to the latest version (may change the range)The lock changes along with it, and the diff shows exactly what changed. Tools like Dependabot and Renovate do this for you, opening one PR per update.
Summary#
package.jsonsays which versions are acceptable; the lock says which version was installed.- Commit the lock and don't delete it to "fix" a problem.
npm ciin CI and in Docker,npm installwhen you want to change dependencies.- The hash guarantees the package didn't change; the lock guarantees a new version doesn't get in without a PR.
- Conflict in the lock: resolve
package.jsonand runnpm install. - One package manager per project.
The lock file isn't a nuisance: it's what guarantees that the code you tested is the code that goes to production.
References#
Read next

Infra11 min read
Datadog from scratch: set it up and read the dashboard

Infra15 min read
How to save tokens in Claude Code with rtk and graphify

Infra13 min read
How to wipe a hard drive or SSD before selling it