Everything you want to know about package-lock.json


previously on

When you happily upgrade NPM to V5. X.x, everything seems to be going well. Eh… Wait, a new file is created automatically! What is this? Package-lock.json。 If you browse it, you will find that it looks like a package. JSON dependency, but it is much longer. You don’t care about it at all, but in the end, you will always encounter various problems such as depending on the wrong version or not finding the dependency. Many people’s solution is to delete package-lock.json and run NPM install again. If so, what is the meaning of package-lock.json? What is its purpose to solve?


  • If you use NPM version 5.0.0 or above, the package-lock.json file will be created automatically.
  • Package lock is used to ensure stable installation and dependency compatibility.
  • To ensure source consistency, youMustSubmit the package lock file.
  • In NPM 5.1. X and above, the weight of package.json is greater than package-lock.json, which solves a big headache source.
  • You don’t need to delete the package lock file manually and then rebuild it with NPM install.
  • Use and follow semver semantic version.


Semantic version

You have to understand semver before you can explore package lock. It is the little hero behind NPM. You can learn how NPM uses it here. Generally speaking, if you are developing an application that can be used by other applications, you must explain how each upgrade will affect the use of third parties. This is what the semantic version wants to convey. There are three parts in a version: X, y, Z, which refer to the large version, the small version, and the missing version. For example, 1.2.3 is big version 1, small version 2 and bugfix version 3. The bugfix version will not affect any function, and the small version change is often to add new functions, and will not affect the use. However, large version changes often lead to incompatibilities at the use level, which need to be adjusted again. (think about every time webback is upgraded!)

Package management

In order to simplify package management, NPM appeared. A project may have hundreds of dependencies, and each dependency has hundreds of dependencies. In order not to fall into dependency hell, NPM can install and manage these dependencies with a few simple commands, which greatly saves time.

When you use NPM to install a package (and save it), a message, including the package name and version, is automatically added to package.json. NPM also supports version wildcards. NPM installs the latest version by default, and then adds a “^” character before its version number. For example “^ 1.2.12”, which indicates that at least version 1.2.12 should be used, and on top of that, any version with the same version number is OK. After all, the small version and bugfix version will not have any impact on the use, so it is safe to use any higher version of the same large version. You can learn more about semver wildcards and the semver calculator of NPM here.

Multiplayer project

The real benefit of package.json is that anyone can use this file to generate a folder that contains all the dependencies required by the project. But let’s see what might go wrong?

Let’s create a new project using express. implementnpm initAfter installing express:npm install express — save。 When I wrote, the maximum version of express was 4.15.4. So “express”: “^ 4.15.4” is written into package.json, and the dependency has been installed. However, the next day, the maintainer of express may have released a bugfix version, so the latest version is 4.15.5. If at this time my colleague clone took this project and executednpm install, because the large version number of 4.15.5 has not changed, the version he installed will be the latest 4.15.5. We all have express installed, but it’s a different version. According to the principle, they are compatible with each other, but it may happen that the bug fix fixed just affects the functions we use, so when we run our own projects separately, different results will appear. This is a problem!



Package lock is to solve the above problems! That is, different results may be installed from the same package.json file. Package lock.json is added after NPM 5. X.x, so it will be generated automatically as long as you do not disable it (Note: you can set package lock = false from. Npmrc).


Package lock includes the package installation version, installation address (URI), hash to verify package integrity, its required subpackages, and dependency list. The package lock entry of express is as follows:

"express": {
      "version": "4.15.4",
      "resolved": "https://registry.npmjs.org/express/-/express-4.15.4.tgz",
      "integrity": "sha1-Ay4iU0ic+PzgJma+yj0R7XotrtE=",
      "requires": {
        "accepts": "1.3.3",
        "array-flatten": "1.1.1",
        "content-disposition": "0.5.2",
        "content-type": "1.0.2",
        "cookie": "0.3.1",
        "cookie-signature": "1.0.6",
        "debug": "2.6.8",
        "depd": "1.1.1",
        "encodeurl": "1.0.1",
        "escape-html": "1.0.3",
        "etag": "1.8.0",
        "finalhandler": "1.0.4",
        "fresh": "0.5.0",
        "merge-descriptors": "1.0.1",
        "methods": "1.1.2",
        "on-finished": "2.3.0",
        "parseurl": "1.3.1",
        "path-to-regexp": "0.1.7",
        "proxy-addr": "1.1.5",
        "qs": "6.5.0",
        "range-parser": "1.2.0",
        "send": "0.15.4",
        "serve-static": "1.12.4",
        "setprototypeof": "1.0.3",
        "statuses": "1.3.1",
        "type-is": "1.6.15",
        "utils-merge": "1.0.0",
        "vary": "1.1.1"

Each package listed under requirements has the same entry under package lock.

So NPM actually uses package-lock.json to decide how to install dependencies!As like as two peas, package-lock, which has written the installation version of the package, addresses the package integrity check and enumerates all the sub dependencies of the package, so the module will be exactly the same result if package-lock is installed.


Since packge lock is used to solve problems, why are there many discussions about its existence and how to prohibit its generation?

Before npm5. X.x, package.json was the only source of truth for projects. Package.json is what it says! NPM users like and are used to maintaining only package.json. However, when package lock appears, it goes against many people’s expectations! If there is the same package and package lock, the modification of package.json will not affect the package lock.

Therefore, after the package.json is changed, the installation does not take effect. It is necessary to remove the package lock and regenerate it into a copy, which causes a lot of controversy. You can see the clue from this interesting reop timeline. Some people think that package.json is still the standard. Some people think that since package lock has been created, the new one is the standard. Finally, the dispute ended with PR Chen 17508. NPM decides.If there are changes on package.json, the weight of package.json will exceed package lock during installation。 This decision was released with NPM v5.1.0 and will be implemented as of July 5, 2017~