skip to content

Install & Lockfile

npm install versus npm ci, the hoisted node_modules tree and dedupe, and what package-lock.json records with integrity hashes. Ignored or badly merged lockfiles cause most 'works on my machine' bugs.

on this pageshow

questions

6

With npm, why does `npm ci` in a CI job fail right after a teammate adds a dependency to `package.json`, and what fixes it?

level: juniorimportance: must knowfreq 40%

answer

  1. a frozen install never writes
  2. two files must agree
  3. the 'in sync' usage error
  4. Missing: name@version from lock file
  5. which command rewrites the lock

basics

~20 s

npm ci installs exactly what package-lock.json records and never writes it, so when package.json declares a dependency the lock lacks it exits with an out-of-sync error. Run npm install locally and commit the updated lock.

solid answer

~40 s

`npm ci` is npm's clean install for automated environments. It requires an existing `package-lock.json`, builds the tree `package.json` asks for, compares it with the lock, and on any difference exits with "`npm ci` can only install packages when your package.json and package-lock.json are in sync", listing each `Missing:` or `Invalid:` entry. It never writes `package.json` or the lock, so it cannot repair the drift itself. The teammate either edited the manifest by hand or ran `npm install` and committed only `package.json`. The fix is to run `npm install` locally, which resolves the new dependency and updates `package-lock.json`, then commit both files together. `npm install` is the command that changes dependencies; `npm ci` reproduces them.

code

bash · 5 lines
bash
npm ci                       # fails: package.json and package-lock.json are not in sync
npm install                  # resolves chrono-fmt and rewrites package-lock.json
git add package.json package-lock.json
git commit -m "Record chrono-fmt in the lockfile"
npm ci                       # now passes, and so will the CI job

go deeper

for a junior

Recall the one-line difference: npm install changes the tree and the lock, npm ci reproduces the lock exactly and stops when the two files disagree. The fix is a local npm install plus committing the lock.

for a middle

Explain what npm ci checks: it builds the tree package.json asks for, compares it with the lock, and only then empties node_modules. Read the Missing and Invalid lines to name the drifted dependency.

for a senior

Treat the failure as the gate working, not a flaky job. Push for package.json and package-lock.json to change together in one commit, and reject pull requests where only one of them moved.

for a principal

Frame the lock as a reviewed artifact: a pipeline that reproduces it exactly costs a little friction per dependency change and buys installs that never differ between machines.

## What `npm ci` checks before it touches anything `npm ci` is npm's **clean install**, meant for test platforms, continuous integration and deployments. It is not a faster `npm install`; it is a different contract. Before it removes or downloads anything, it works through three steps in order: 1. **Load `package-lock.json`.** With no lockfile it stops at once with a usage error: it "can only install with an existing package-lock.json", and you are told to run an install first. 2. **Build the tree `package.json` asks for** under the current configuration, and compare that tree entry by entry with the one the lock records. 3. **Refuse on any difference.** The headline is "`npm ci` can only install packages when your package.json and package-lock.json are in sync. Please update your lock file with `npm install` before continuing.", followed by one line per mismatch: `Missing: [email protected] from lock file` for a dependency the lock has never heard of, or `Invalid: lock file's [email protected] does not satisfy [email protected]` when a range moved past the locked version. Only when the lock validates does `npm ci` empty the `node_modules` folders (the root's and each workspace's) and install exactly the versions the lock lists. A failed validation therefore leaves the runner's existing folder untouched. ## Why it refuses instead of fixing - **It never writes `package.json` or `package-lock.json`.** npm describes the install as essentially frozen, so there is no code path that could add the missing entry. - **It installs whole projects only.** Individual dependencies cannot be added with `npm ci`; that is what `npm install <name>` is for. - **The mismatch is information.** It means the commit is incomplete: the manifest gained a dependency whose resolved version, tarball URL and integrity hash were never recorded and reviewed. - **A silent repair would hide the problem.** A runner that re-resolved on its own would install whatever version the registry served that minute and write a lock onto a machine that is thrown away after the job. ## `npm install` versus `npm ci` | | `npm install` (no arguments) | `npm ci` | |---|---|---| | Needs a lockfile | No; it creates one | Yes; errors without one | | Lock disagrees with `package.json` | `package.json` wins: npm resolves and updates the lock | Exits with the out-of-sync error | | Writes `package.json` / lock | Yes, by default | Never | | Existing `node_modules` | Reused and updated in place | Emptied after the lock validates | | Add one package | Yes, `npm install chrono-fmt` | No, whole project only | | Where it belongs | A developer machine, when dependencies change | CI, test and deployment | When the lock's versions still satisfy every range, `npm install` uses them exactly, so on an unchanged project both commands produce the same tree. They differ only in what they do when the two files disagree. ## Repairing the drift 1. Check out the branch whose CI run failed. 2. Run `npm install` with no arguments. npm compares `package.json` with the lock, resolves the new dependency within its declared range, and writes the new `packages` entries into `package-lock.json`. 3. Look at the lock diff: the new dependency, plus anything it pulls in, each with a `version`, `resolved` URL and `integrity` hash. 4. Commit `package.json` and `package-lock.json` together. 5. Optionally run `npm ci` locally; it should now pass, and so will CI. If you only need the lock repaired and not a working `node_modules`, `npm install --package-lock-only` updates `package-lock.json` without downloading packages. ## Keeping it from coming back - Make it a review rule: a pull request that changes a dependency section of `package.json` and not `package-lock.json` is incomplete. - Do not "fix" the pipeline by switching it to `npm install`; that removes the check and lets every CI run resolve its own tree. - Do not delete the lock to make the error go away; without a lock every range is resolved from scratch. - If the lock was written with flags that change the shape of the tree, `npm ci` needs those same flags, which is why such settings belong in the committed project `.npmrc`. - Run `npm ci` in pull-request checks, not only on the main branch, so an incomplete commit fails where its author is still looking at it. The out-of-sync error is one of the cheapest failures a pipeline can give you: it names the package, it fires before anything is deleted or downloaded, and the fix is one local command and one commit.

  • Why not switch the CI job to `npm install` so it stops failing?
    Because `npm install` would quietly resolve the missing dependency on the runner, at whatever version the registry serves that day, and write a lock nobody commits. CI would then test a tree no developer has, and the next run could pick a different one. The failure is telling you the commit is incomplete; fix the commit, not the command.
  • What does `npm ci` do to an existing `node_modules`, and when?
    It empties every `node_modules` folder, the root's and each workspace's, and installs from scratch, but only after it has loaded the lock and confirmed that it matches `package.json`. An out-of-sync lock fails the job before anything is removed. That is why `npm ci` is slower on a warm laptop but predictable on a fresh runner.
  • Can you update only `package-lock.json`, without downloading into `node_modules`?
    Yes: `npm install --package-lock-only` resolves against `package.json` and writes the lock without checking or populating `node_modules`. It is handy when you only need a correct lock in the commit; `npm ci` will accept the result as long as the two files agree.

  • npm ci updates package-lock.json when it disagrees with package.json.
  • Switching the pipeline back to npm install is the right fix for this error.
  • npm ci can add a single new package, the same way npm install does.
  • npm ci works without a lockfile and simply resolves from package.json.
  • Clearing the runner's node_modules makes the out-of-sync error go away.
open as a page

With npm, how should you resolve a Git merge conflict in `package-lock.json` after two branches each added dependencies?

level: middleimportance: must knowfreq 24%

basics

~20 s

Resolve package.json by hand first, then take one side's package-lock.json whole and run npm install, which keeps every locked version that still satisfies the merged ranges and resolves the rest. Commit both files and confirm with npm ci.

open as a page

With npm, what does `npm audit fix` change in a project, what does it leave alone, and when does `--force` cross a major version?

level: middleimportance: should knowfreq 20%

basics

~20 s

npm audit fix moves vulnerable packages to non-vulnerable versions that the declared ranges already allow. A fix that needs a range change is left alone unless you pass --force, which may install a SemVer-major update of a direct dependency.

open as a page

With npm, why can `npm ls` show two copies of one library at different majors, and what can `npm explain` and `npm dedupe` do about it?

level: middleimportance: should knowfreq 18%

basics

~20 s

npm's default hoisted layout gives each package name one top-level slot; a dependent whose range rejects that copy gets its own nested copy. npm explain shows which chain demands each copy; npm dedupe merges copies only when one version satisfies every range.

open as a page

With npm, a lockfile was written by `npm install --legacy-peer-deps` on a laptop and `npm ci` now fails in CI — why, and what is the durable fix?

level: seniorimportance: should knowfreq 12%

basics

~20 s

--legacy-peer-deps changes the tree npm builds, so npm ci without it computes a different tree than the lock records and fails. Commit legacy-peer-deps=true to the project .npmrc, or fix the peer conflict and regenerate the lock without it.

open as a page

On npm 12, with `min-release-age=7` in the project `.npmrc`, why does `npm audit fix` leave a package vulnerable and exit non-zero?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

min-release-age=7 lets npm install only versions published more than seven days ago. A patch released yesterday falls inside that window, so npm 12 keeps the vulnerable version, warns that the fix was blocked and exits non-zero.

open as a page