A scanner that reads npm projects should handle lockfileVersion 1, 2 and 3. Version 1 comes from npm 5 and 6, version 2 from npm 7 and 8, and version 3 from npm 9 and later. Old repositories mix them, so test a file of each kind before you trust a clean result.
The three formats
The npm documentation describes the versions this way:
| lockfileVersion | Used by | Notes |
|---|---|---|
| Missing | npm before v5 | Ancient shrinkwrap style |
| 1 | npm v5 and v6 | Hierarchical dependencies section |
| 2 | npm v7 and v8 | Backwards compatible with v1 |
| 3 | npm v9 and later | Backwards compatible with npm v7 |
Two sections matter. The packages section maps each package location to its details, with the root project keyed as an empty string. Entries carry fields such as version, resolved, integrity and flags like dev and optional. The dependencies section is legacy data kept for version 1 support, and npm v7 and later ignore it when packages is present.
Why this matters for accuracy
A scanner built for one layout might read the wrong section for another. Possible failures:
- It reads only
dependencies, which in a version 3 file does not exist, and finds nothing. - It reads only
packages, and misses a version 1 file entirely. - It ignores the dev flag and reports test tooling as production risk, or the reverse.
None of these would raise an error. You would see a short list and assume the project is small.
A format coverage test
- Take one project and regenerate its lockfile under each npm major version you can run, or find real repositories that carry each version.
- Scan all three with the same tool.
- Compare the component counts. They should be close, with differences you can explain.
- Check how each file flags dev only and optional packages in the report.
- Add a check in CI that fails when a lockfile yields zero components.
The same idea applies to other package managers whose formats have changed over time. See package lock files and their security implications for background on why the file matters.
What to ask a vendor
- Which lockfile versions are parsed, and what happens with an unknown one?
- Is the dev flag preserved, so you can filter?
- Does the report list the file it read, so you can see the source of each finding?
Safeguard's SBOM and dependency scanning lists components with their source file, and you can try a lockfile at https://gold.safeguard.sh/scan.
Try it yourself
Open the demo and look at how each component is attributed. Ask yourself which file you would need to change to remove it.
Click through it at your own pace, or open it full screen.
Quick check
Which npm version writes lockfileVersion 3?
npm v9 and later, according to the npm documentation.
Is the dependencies section still used?
It is legacy data kept for version 1 support. npm v7 and later ignore it when a packages section exists.
Sources
Last reviewed: 19 October 2026.
