All articles

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.

Also in Português, Español, Français

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.

The classic “works on my machine”: same package.json, different versions

TL;DR#

  • package.json accepts version ranges (^2.0.0 means "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.json installs different versions on different days. In my test, I got 2.1.1 with the lock and 2.1.3 without it.
  • Commit the lock file and never delete it to "fix" a problem.
  • In CI, use npm ci (or pnpm install --frozen-lockfile, or yarn 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.json and run npm install again. 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.3
The package.json range accepts several versions. The lock picks one and doesn't change it anymore

This 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 install respects the lock as long as it matches package.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 ci deletes node_modules and installs exactly what's in the lock. It never changes the lock. If package.json and 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 managerLock fileInstall without touching the lock
npmpackage-lock.jsonnpm ci
pnpmpnpm-lock.yamlpnpm install --frozen-lockfile
Yarn (2 or newer)yarn.lockyarn install --immutable
Yarn 1yarn.lockyarn 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.

The lock doesn't know whether a package is safe. It just doesn't let a new version in without someone asking

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:

  1. resolve the package.json conflict by hand (it's short and readable);
  2. 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 395ms

Then 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.json says which versions are acceptable; the lock says which version was installed.
  • Commit the lock and don't delete it to "fix" a problem.
  • npm ci in CI and in Docker, npm install when 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.json and run npm 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#

  • Infra
  • npm
  • pnpm
  • yarn
  • lock file
  • ci
  • security

Written by

Software engineer and designer. I write about what I run into while building apps, APIs and products.