What is package-lock.json?
© https://nodejs.org/en/

What is package-lock.json?

Avoid installing different versions from the same module

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

This article is based on Node v16.15.1 and NPM 8.11.0.

This tutorial explains what the difference between package.json and package-lock.json is, and why package-lock.json can help to avoid installing modules with different versions. If you are not sure what the package.json is responsible for, check out this article - The basics of Package.json.

How package-lock.json manages the dependency tree

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

package-lock.json is a file generated by npm (since v5 2017), and it locks package dependencies and their sub-dependencies. It tracks only top-level dependencies, and their associated versions. Sounds simple right? Though each of these top-level dependencies can also have their own dependencies, and each of these can also have their own dependencies and so on. This relationship between all the dependencies and sub-dependencies in a project is called the dependency tree. The dependency tree represents every module our project depends on and what version is required.

Installing a dependency with npm actually fetches all the needed dependencies, and installs them into the node_modules/ folder. The package-lock.json file is a snapshot of our entire dependency tree and all the information npm needs to recreate the state of the node_modules/ folder. Also, when a package-lock.json file is present, npm install will install the exact versions specified.

The package-lock.json is not meant to be human-readable, and it's not meant to be edited manually. The npm CLI generates and manages it for us automatically.

Track package-lock.json

The package-lock.json file needs to be committed to version control (GIT) to make sure the same dependency tree is used every time. The benefit of committing the package-lock file to version control is tracking the state of the node_modules/ folder without having to commit the folder itself to version control. Never commit the node-modules folder. It is not intended to be committed, it's too big, and the state is already tracked.

Whenever we run a npm command that changes dependencies, like npm install <PACKAGE> or npm uninstall <PACKAGE> or npm update or any other command that alters dependencies, the package-lock.json file will be updated to reflect the state of the dependency tree.


Locking dependencies is not a new concept in the Node.js ecosystem or in the programming world. The package-lock file behaves nearly like the already existing npm-shrinkwrap.json, which was how to lock a package before npm v5. The only difference is that the package-lock.json is ignored by npm when publishing to the NPM registry. If you want to lock your dependencies, when publishing a package you have to use npm-shrinkwrap.json. You should only have one of these files in your root directory. If both are present npm-shrinkwrap takes precedent. The recommended use-case for npm-shrinkwrap.json is applications deployed through the publishing process on the NPM registry.

To create a npm-shrinkwrap file, run npm shrinkwrap. This command renames your package-lock to npm-shrinkwrap. The files are functionally the same. npm-shrinkwrap should be used when publishing to the NPM registry.


  • package-lock.json is a snapshot of the entire dependency tree (all packages, all dependencies. all resolved version numbers)
  • It's a safeguard against dependency drifting between installs.
  • package-lock.json is updated automatically on dependency changes.
  • It should be committed to version control to ensure the same dependencies on install.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

NPM package-lock, NPM shrinkwrap, Node, HeyNode

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑