The package-lock-only option tells npm to work from package-lock.json alone and ignore node_modules. For install and update it only updates the lockfile instead of downloading dependencies, and for list and query it reports the tree described by the lockfile. It is useful for lockfile changes in CI or automation.
What the docs say
The npm config definition says: if set to true, the current operation will only use package-lock.json, ignoring node_modules. For update, only the lockfile is updated instead of checking node_modules and downloading dependencies. For list, output is based on the tree in the lockfile rather than the contents of node_modules. The install documentation says the same about install.
npm install some-package --package-lock-only
npm ls --package-lock-only
npm query "#some-package" --package-lock-only
Good uses
| Use | Why lockfile-only helps |
|---|---|
| A bot or script that bumps a version | No need to install the whole tree just to rewrite the lockfile |
| Recording a linked dependency | The npm link docs suggest it for adding a new dependency recorded as a link |
| Inventory in a build step | Listing from the lockfile is quick and does not need node_modules |
| Reviewing a branch you have not installed | You can query the tree without a full install |
What you lose
Because npm does not look at node_modules, it cannot tell you what is actually on disk. If someone edited a file in node_modules, or an install is partial, lockfile-only output will not show it. The npm query docs add one more detail: in this mode information that comes from each dependency's package.json, such as description, homepage or engines, is not in the result.
Skipping the install also skips whatever the install would have verified or run. Treat the changed lockfile as untrusted input until you review it. A lockfile-only update can still resolve to a new version of anything within your ranges.
A safe pattern for automated bumps
- Run the update with lockfile-only in a throwaway branch.
- Diff the lockfile. Look for new packages, changed resolved hosts and changed integrity values. Our guide to reviewing a lockfile-only security hotfix covers the checks.
- Run the real install in CI with npm ci, which fails when package.json and the lockfile disagree and never writes to either file.
- Run tests and your dependency scan on that install, not on the lockfile alone.
- Merge only after both pass.
When not to use it
Do not use it to conclude that a build is reproducible. Reproducibility comes from the frozen install in CI. And do not use it where you need to know what scripts a package would run, since nothing installs.
Where Safeguard fits
Safeguard's dependency scanning reads the lockfile directly, so the inventory it builds matches what a lockfile-only command sees, and policies and gates can check a bump before it merges. A free scan is at https://gold.safeguard.sh/scan.
Quick check
Does package-lock-only install packages?
No. It uses only the lockfile and ignores node_modules, so nothing is downloaded for update, and list shows the lockfile's tree.
Is a lockfile-only update safe to merge without an install?
No. Review the diff, then run npm ci and your checks. A lockfile-only update can still resolve to new versions.
Sources
- npm config definitions
- npm install documentation
- npm query documentation
- npm link documentation
- npm ci documentation
Last reviewed: 19 October 2026.
