--package-lock-only updates the lockfile without installing the dependency tree into node_modules. Treat it as a dependency-resolution operation, not as a way to reconstruct an exact inventory of whatever happens to be installed locally.
Reproduce the boundary in a disposable fixture
Separate dependency resolution metadata from the current node_modules directory.
Use a new empty temporary directory for this fixture. The example creates only local test data. Commands marked with example.invalid do not identify a real service.
mkdir demo
cd demo
printf '%s
' '{"name":"lock-fixture","version":"1.0.0"}' > package.json
npm install --package-lock-only --ignore-scripts --no-audit --no-fund --offline
test -f package-lock.json
test ! -d node_modules
node -e 'const fs=require("node:fs");const p=JSON.parse(fs.readFileSync("package-lock.json"));console.log({name:p.name,lockfileVersion:p.lockfileVersion})' Observed result
up to date in 246ms
{ name: 'lock-fixture', lockfileVersion: 3 }What the result means
This dependency-free fixture creates a lockfile while leaving node_modules absent. Offline mode makes the example independent of registry access. It demonstrates the separation between lock metadata and installed packages, not how a particular dependency range resolves today. The lockfile format version is read from the result rather than assumed from an old tutorial.
Choose the correction for your workflow
Before using the flag in a real project, inspect the manifest, current lock and npm version. Review the resulting lockfile diff as a resolution change. The current npm install documentation states that package-lock-only ignores node_modules and updates the lock rather than checking or downloading installed modules. If the task is to reproduce an approved dependency tree, use the reviewed manifest and lock with npm ci in a disposable environment. If the task is an inventory, inspect the installed tree with the appropriate listing tool and preserve its provenance separately.
Limits and the next check
For a project with dependencies, lockfile calculation can need registry metadata and can change selected versions within allowed constraints. Offline success for this empty fixture does not promise an offline operation for arbitrary projects. --ignore-scripts is used here to keep the example inert; the project actual installation policy may differ. Do not delete the existing lockfile or claim a new lock exactly describes old local packages without verifying that independently.
Related: Compare the related workflow boundary.
This isolated example was executed on macOS on November 10, 2026 (KST). Available tools: node v26.5.0, git git version 2.39.3 (Apple Git-145), npm 11.17.0, jq jq-1.7.1-apple. Shell fixtures use Bash and repository-path identity uses Python 3. This checks the illustrated contract, not your project, host service or every tool version.