Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

package-lock.json keeps flipping its lockfileVersion between npm versions

Errorpackage-lock.json shows lockfileVersion 2 on one machine and 3 on another

Short answer

lockfileVersion follows the npm that wrote the file: npm 5 and 6 write 1, npm 7 and 8 write 2, npm 9 and later write 3. When teammates run different npm versions the field changes in every diff. Align npm versions, or set lockfile-version to the format you want.

  • Applies to npm 9, npm 10, npm 11, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the npm version with the version in the lockfile.

    npm --version
    grep lockfileVersion package-lock.json
  2. 2Match what you see, then jump to its fix

    1. 1The lockfile diff is large and only machines with another npm version produce itDifferent npm versions write different lockfile formatsFix
    2. 2An older npm in CI or a build image cannot use the version 3 lockfileYou need a format an older npm can readFix
    3. 3npm config get lockfile-version prints a number although you never passed a flagA lockfile-version value in .npmrc forces the formatFix

What does the error look like?

  • package-lock.json shows lockfileVersion 2 on one machine and 3 on another
  • A pull request rewrites the whole lockfile after npm install

Cause 1 of 3

Different npm versions write different lockfile formats

1Check

Per the npm docs, npm 5 and 6 use version 1, npm 7 and 8 use version 2, and npm 9 and above use version 3. Without a setting, npm keeps the current lockfile version and converts a version 1 file to 3.

node --version && npm --version

2Fix

Make everyone, and CI, run the same npm version, and write that version down in the team's setup notes. Check it with the command below.

npm --version

3Verify

Run npm install on two machines and compare the lockfile.

git diff --stat package-lock.json

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

You need a format an older npm can read

1Check

The lockfile-version setting accepts 1, 2 or 3. Version 2 holds both the old and new data and works for npm 7 and 8; version 3 is smaller but not compatible with older npm.

npm config get lockfile-version

2Fix

Write the older format on purpose, for the project.

npm install --lockfile-version=2

3Verify

The field in the lockfile changed to the requested version.

grep lockfileVersion package-lock.json

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

A lockfile-version value in .npmrc forces the format

1Check

A project or user .npmrc can set lockfile-version. The default is to keep whatever version the lockfile already has.

cat .npmrc ~/.npmrc 2>/dev/null
npm config get lockfile-version

2Fix

Remove the stale line, or put the format you want in the project .npmrc so all machines agree.

# .npmrc in the project
lockfile-version=3

3Verify

The setting now reads the same on every machine.

npm config get lockfile-version

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Agree on one Node.js and npm version for the team and for CI.
  • Commit the lockfile in its own pull request when you change the npm version.
  • Use npm ci in CI so the lockfile is read and not rewritten.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.