1--- 2title: package-lock.json 3section: 5 4description: A manifestation of the manifest 5--- 6 7### Description 8 9`package-lock.json` is automatically generated for any operations where npm 10modifies either the `node_modules` tree, or `package.json`. It describes the 11exact tree that was generated, such that subsequent installs are able to 12generate identical trees, regardless of intermediate dependency updates. 13 14This file is intended to be committed into source repositories, and serves 15various purposes: 16 17* Describe a single representation of a dependency tree such that 18 teammates, deployments, and continuous integration are guaranteed to 19 install exactly the same dependencies. 20 21* Provide a facility for users to "time-travel" to previous states of 22 `node_modules` without having to commit the directory itself. 23 24* Facilitate greater visibility of tree changes through readable source 25 control diffs. 26 27* Optimize the installation process by allowing npm to skip repeated 28 metadata resolutions for previously-installed packages. 29 30* As of npm v7, lockfiles include enough information to gain a complete 31 picture of the package tree, reducing the need to read `package.json` 32 files, and allowing for significant performance improvements. 33 34### `package-lock.json` vs `npm-shrinkwrap.json` 35 36Both of these files have the same format, and perform similar functions in 37the root of a project. 38 39The difference is that `package-lock.json` cannot be published, and it will 40be ignored if found in any place other than the root project. 41 42In contrast, [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) allows 43publication, and defines the dependency tree from the point encountered. 44This is not recommended unless deploying a CLI tool or otherwise using the 45publication process for producing production packages. 46 47If both `package-lock.json` and `npm-shrinkwrap.json` are present in the 48root of a project, `npm-shrinkwrap.json` will take precedence and 49`package-lock.json` will be ignored. 50 51### Hidden Lockfiles 52 53In order to avoid processing the `node_modules` folder repeatedly, npm as 54of v7 uses a "hidden" lockfile present in 55`node_modules/.package-lock.json`. This contains information about the 56tree, and is used in lieu of reading the entire `node_modules` hierarchy 57provided that the following conditions are met: 58 59- All package folders it references exist in the `node_modules` hierarchy. 60- No package folders exist in the `node_modules` hierarchy that are not 61 listed in the lockfile. 62- The modified time of the file is at least as recent as all of the package 63 folders it references. 64 65That is, the hidden lockfile will only be relevant if it was created as 66part of the most recent update to the package tree. If another CLI mutates 67the tree in any way, this will be detected, and the hidden lockfile will be 68ignored. 69 70Note that it _is_ possible to manually change the _contents_ of a package 71in such a way that the modified time of the package folder is unaffected. 72For example, if you add a file to `node_modules/foo/lib/bar.js`, then the 73modified time on `node_modules/foo` will not reflect this change. If you 74are manually editing files in `node_modules`, it is generally best to 75delete the file at `node_modules/.package-lock.json`. 76 77As the hidden lockfile is ignored by older npm versions, it does not 78contain the backwards compatibility affordances present in "normal" 79lockfiles. That is, it is `lockfileVersion: 3`, rather than 80`lockfileVersion: 2`. 81 82### Handling Old Lockfiles 83 84When npm detects a lockfile from npm v6 or before during the package 85installation process, it is automatically updated to fetch missing 86information from either the `node_modules` tree or (in the case of empty 87`node_modules` trees or very old lockfile formats) the npm registry. 88 89### File Format 90 91#### `name` 92 93The name of the package this is a package-lock for. This will match what's 94in `package.json`. 95 96#### `version` 97 98The version of the package this is a package-lock for. This will match 99what's in `package.json`. 100 101#### `lockfileVersion` 102 103An integer version, starting at `1` with the version number of this 104document whose semantics were used when generating this 105`package-lock.json`. 106 107Note that the file format changed significantly in npm v7 to track 108information that would have otherwise required looking in `node_modules` or 109the npm registry. Lockfiles generated by npm v7 will contain 110`lockfileVersion: 2`. 111 112* No version provided: an "ancient" shrinkwrap file from a version of npm 113 prior to npm v5. 114* `1`: The lockfile version used by npm v5 and v6. 115* `2`: The lockfile version used by npm v7 and v8. Backwards compatible to v1 116 lockfiles. 117* `3`: The lockfile version used by npm v9 and above. Backwards compatible to npm v7. 118 119npm will always attempt to get whatever data it can out of a lockfile, even 120if it is not a version that it was designed to support. 121 122#### `packages` 123 124This is an object that maps package locations to an object containing the 125information about that package. 126 127The root project is typically listed with a key of `""`, and all other 128packages are listed with their relative paths from the root project folder. 129 130Package descriptors have the following fields: 131 132* version: The version found in `package.json` 133 134* resolved: The place where the package was actually resolved from. In 135 the case of packages fetched from the registry, this will be a url to a 136 tarball. In the case of git dependencies, this will be the full git url 137 with commit sha. In the case of link dependencies, this will be the 138 location of the link target. `registry.npmjs.org` is a magic value meaning 139 "the currently configured registry". 140 141* integrity: A `sha512` or `sha1` [Standard Subresource 142 Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) 143 string for the artifact that was unpacked in this location. 144 145* link: A flag to indicate that this is a symbolic link. If this is 146 present, no other fields are specified, since the link target will also 147 be included in the lockfile. 148 149* dev, optional, devOptional: If the package is strictly part of the 150 `devDependencies` tree, then `dev` will be true. If it is strictly part 151 of the `optionalDependencies` tree, then `optional` will be set. If it 152 is both a `dev` dependency _and_ an `optional` dependency of a non-dev 153 dependency, then `devOptional` will be set. (An `optional` dependency of 154 a `dev` dependency will have both `dev` and `optional` set.) 155 156* inBundle: A flag to indicate that the package is a bundled dependency. 157 158* hasInstallScript: A flag to indicate that the package has a `preinstall`, 159 `install`, or `postinstall` script. 160 161* hasShrinkwrap: A flag to indicate that the package has an 162 `npm-shrinkwrap.json` file. 163 164* bin, license, engines, dependencies, optionalDependencies: fields from 165 `package.json` 166 167#### dependencies 168 169Legacy data for supporting versions of npm that use `lockfileVersion: 1`. 170This is a mapping of package names to dependency objects. Because the 171object structure is strictly hierarchical, symbolic link dependencies are 172somewhat challenging to represent in some cases. 173 174npm v7 ignores this section entirely if a `packages` section is present, 175but does keep it up to date in order to support switching between npm v6 176and npm v7. 177 178Dependency objects have the following fields: 179 180* version: a specifier that varies depending on the nature of the package, 181 and is usable in fetching a new copy of it. 182 183 * bundled dependencies: Regardless of source, this is a version number 184 that is purely for informational purposes. 185 * registry sources: This is a version number. (eg, `1.2.3`) 186 * git sources: This is a git specifier with resolved committish. (eg, 187 `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`) 188 * http tarball sources: This is the URL of the tarball. (eg, 189 `https://example.com/example-1.3.0.tgz`) 190 * local tarball sources: This is the file URL of the tarball. (eg 191 `file:///opt/storage/example-1.3.0.tgz`) 192 * local link sources: This is the file URL of the link. (eg 193 `file:libs/our-module`) 194 195* integrity: A `sha512` or `sha1` [Standard Subresource 196 Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) 197 string for the artifact that was unpacked in this location. For git 198 dependencies, this is the commit sha. 199 200* resolved: For registry sources this is path of the tarball relative to 201 the registry URL. If the tarball URL isn't on the same server as the 202 registry URL then this is a complete URL. `registry.npmjs.org` is a magic 203 value meaning "the currently configured registry". 204 205* bundled: If true, this is the bundled dependency and will be installed 206 by the parent module. When installing, this module will be extracted 207 from the parent module during the extract phase, not installed as a 208 separate dependency. 209 210* dev: If true then this dependency is either a development dependency ONLY 211 of the top level module or a transitive dependency of one. This is false 212 for dependencies that are both a development dependency of the top level 213 and a transitive dependency of a non-development dependency of the top 214 level. 215 216* optional: If true then this dependency is either an optional dependency 217 ONLY of the top level module or a transitive dependency of one. This is 218 false for dependencies that are both an optional dependency of the top 219 level and a transitive dependency of a non-optional dependency of the top 220 level. 221 222* requires: This is a mapping of module name to version. This is a list of 223 everything this module requires, regardless of where it will be 224 installed. The version should match via normal matching rules a 225 dependency either in our `dependencies` or in a level higher than us. 226 227* dependencies: The dependencies of this dependency, exactly as at the top 228 level. 229 230### See also 231 232* [npm shrinkwrap](/commands/npm-shrinkwrap) 233* [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) 234* [package.json](/configuring-npm/package-json) 235* [npm install](/commands/npm-install) 236