Question
npm ci lockfileVersion mismatch across npm releases
Rey Moss
0 reputation · 22 Apr 2022, 06:18 UTC
123.3K views1
Loading…
0 reputation · 22 Apr 2022, 06:18 UTC
A team wants a single package-lock.json to drive identical installs with npm ci across local workstations and CI runners.
npm records lockfileVersion in the lockfile, and npm 7 and later use version 2 or 3 while earlier releases use version 1. It is unclear whether npm ci rejects a lockfile written by a different major npm release, or whether it silently rewrites the lockfile during installation. The --prefer-offline flag is intended to avoid network calls, but it is not clear whether cached packages skip integrity hash validation against the lockfile.
Does npm ci fail when lockfileVersion differs from the running npm version's expected format? Does npm ci update package-lock.json when installed from an older lockfileVersion? With --prefer-offline, does npm ci still verify package integrity hashes from package-lock.json?
35775 reputation · 22 Apr 2022, 10:16 UTC
Whether npm ci fails or succeeds during a lockfileVersion mismatch depends entirely on the direction of the version gap (older vs. newer).
If you run npm ci using npm 7+ with a package-lock.json created by npm 6 (lockfileVersion: 1), the command will not fail. Instead, npm will automatically convert the lockfile to the current version (Version 2 or 3) during the installation process and rewrite the package-lock.json file on disk.
If you run npm ci using npm 6 with a lockfile created by npm 7+ (lockfileVersion: 2 or 3), the command will fail. Older versions of npm cannot parse the newer lockfile formats and will throw an error indicating that the lockfile version is unsupported.
The --prefer-offline flag does not bypass security checks. While it instructs npm to use the local cache instead of making network requests to the registry, npm ci still verifies the integrity hashes of the cached packages against the hashes recorded in package-lock.json. If a cached package is corrupted or does not match the lockfile hash, the installation will fail regardless of the offline flag.
To ensure identical installs across local workstations and CI runners without silent lockfile rewrites, follow these steps:
npm.nvmrc file).npm install once on a machine with the target npm version to migrate the lockfileVersion to the current standard.package-lock.json to version control. This prevents npm ci from needing to perform a conversion during the CI pipeline.This behavior is based on the standard operation of npm 6, 7, 8, and 9. To verify your specific environment, you can run the following scoped test:
# Check current npm version
npm -v
# Attempt a clean install
rm -rf node_modules
npm ci --prefer-offline
# Verify if the lockfile was modified after the run
git status package-lock.jsonDiagnostic Note: To provide a more specific recommendation, please clarify if your CI environment is restricted to a specific Node.js LTS version that bundles an older npm release.
Use comments to ask for clarification. Post a solution as an answer.
6,660 reputation · 22 Apr 2022, 17:13 UTC
The lockfileVersion integer is not the only compatibility gate. npm 6 writes version 1 lockfiles without the top-level packages map that npm 7+ uses during npm ci, so a newer client can read the file yet still abort or resolve a different tree. npm ci never silently rewrites the lockfile. For --prefer-offline, integrity hash validation still runs against cached tarballs; it only changes download preference. Confirm with git diff package-lock.json after a scratch install.