A lockfile records the exact versions of every dependency your project resolved, so later installs produce the same result even if newer versions have been published. Commit it. Without it, two installs of the same project on different days can pull different code.
What a lockfile holds
Using npm as the example, package-lock.json is generated whenever npm changes the node_modules tree or package.json. Per the npm documentation, it records:
- the name and version of your project
- for each package, its version, where it was resolved from (registry URL, git commit or link target), and an integrity hash of the downloaded artifact
- flags showing whether a package is a dev, optional, bundled or install-script dependency
- fields copied from each package's own
package.json, such asdependencies,bin,licenseandengines
Other ecosystems have their own files with the same job.
Why commit it
npm gives these reasons:
- teammates, deployments and CI installs get identical dependencies
- you can return to earlier dependency states without committing
node_modules - changes to the dependency tree show up as readable diffs in version control
- npm can skip repeated metadata lookups, which speeds up installs
The security angle
The integrity hash is the part security teams care about. If the bytes served for a package version change, the hash no longer matches and the install can fail instead of silently accepting different code.
A committed lockfile also turns dependency updates into reviewable changes. A new package appearing in a pull request diff is something a person can notice. For more on this, see our guide to lockfile security practices for npm.
Habits that make it work
- Use the install command designed to follow the lockfile exactly in CI, not one that rewrites it.
- Review lockfile changes in pull requests as carefully as code changes.
- Update dependencies on purpose, in small batches, so a diff stays readable.
- Do not hand edit it. Regenerate it with the tool.
Libraries versus applications
Some teams skip lockfiles for libraries because consumers resolve versions themselves. Even then, your own CI benefits from a locked tree when you test. Check your ecosystem's guidance for what gets published.
A lockfile is the raw material for an SBOM. Safeguard scans lockfiles and manifests for known vulnerable dependencies. A free scan is at gold.safeguard.sh/scan.
Quick check
Does a lockfile stop a malicious package from being installed?
No. It fixes versions and checks integrity. If you lock a bad version, you keep the bad version. Scanning and review still matter.
Should I commit node_modules instead?
Usually no. The lockfile lets you recreate the tree without committing it.
Sources
Last reviewed: 19 October 2026.
