1NPM-UPDATE(1) NPM-UPDATE(1)
2
6 npm-update - Update packages
7 Synopsis
9 npm update [<pkg>...]
10 aliases: up, upgrade, udpate
12 Description
14 This command will update all the packages listed to the latest version
15 (specified by the tag config ⟨/using-npm/config#tag⟩), respecting the
16 semver constraints of both your package and its dependencies (if they
17 also require the same package).
18 It will also install missing packages.
20 If the -g flag is specified, this command will update globally in‐
22 stalled packages.
23 If no package name is specified, all packages in the specified location
25 (global or local) will be updated.
26 Note that by default npm update will not update the semver values of
28 direct dependencies in your project package.json, if you want to also
29 update values in package.json you can run: npm update --save (or add
30 the save=true option to a npm help "configuration file" to make that
31 the default behavior).
32 Example
34 For the examples below, assume that the current package is app and it
35 depends on dependencies, dep1 (dep2, .. etc.). The published versions
36 of dep1 are:
37 {
39 "dist-tags": { "latest": "1.2.2" },
40 "versions": [
41 "1.2.2",
42 "1.2.1",
43 "1.2.0",
44 "1.1.2",
45 "1.1.1",
46 "1.0.0",
47 "0.4.1",
48 "0.4.0",
49 "0.2.0"
50 ]
51 }
52 Caret Dependencies
54 If app's package.json contains:
55 "dependencies": {
57 "dep1": "^1.1.1"
58 }
59 Then npm update will install dep1@1.2.2, because 1.2.2 is latest and
61 1.2.2 satisfies ^1.1.1.
62 Tilde Dependencies
64 However, if app's package.json contains:
65 "dependencies": {
67 "dep1": "~1.1.1"
68 }
69 In this case, running npm update will install dep1@1.1.2. Even though
71 the latest tag points to 1.2.2, this version do not satisfy ~1.1.1,
72 which is equivalent to >=1.1.1 <1.2.0. So the highest-sorting version
73 that satisfies ~1.1.1 is used, which is 1.1.2.
74 Caret Dependencies below 1.0.0
76 Suppose app has a caret dependency on a version below 1.0.0, for exam‐
77 ple:
78 "dependencies": {
80 "dep1": "^0.2.0"
81 }
82 npm update will install dep1@0.2.0, because there are no other versions
84 which satisfy ^0.2.0.
85 If the dependence were on ^0.4.0:
87 "dependencies": {
89 "dep1": "^0.4.0"
90 }
91 Then npm update will install dep1@0.4.1, because that is the highest-
93 sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0)
94 Subdependencies
96 Suppose your app now also has a dependency on dep2
97 {
99 "name": "my-app",
100 "dependencies": {
101 "dep1": "^1.0.0",
102 "dep2": "1.0.0"
103 }
104 }
105 and dep2 itself depends on this limited range of dep1
107 {
109 "name": "dep2",
110 "dependencies": {
111 "dep1": "~1.1.1"
112 }
113 }
114 Then npm update will install dep1@1.1.2 because that is the highest
116 version that dep2 allows. npm will prioritize having a single version
117 of dep1 in your tree rather than two when that single version can sat‐
118 isfy the semver requirements of multiple dependencies in your tree. In
119 this case if you really did need your package to use a newer version
120 you would need to use npm install.
121 Updating Globally-Installed Packages
123 npm update -g will apply the update action to each globally installed
124 package that is outdated -- that is, has a version that is different
125 from wanted.
126 Note: Globally installed packages are treated as if they are installed
128 with a caret semver range specified. So if you require to update to
129 latest you may need to run npm install -g [<pkg>...]
130 NOTE: If a package has been upgraded to a version newer than latest, it
132 will be downgraded.
133 Configuration
135 save
136 • Default: true unless when using npm update where it defaults to
137 false
138 • Type: Boolean
140 Save installed packages to a package.json file as dependencies.
143 When used with the npm rm command, removes the dependency from pack‐
145 age.json.
146 Will also prevent writing to package-lock.json if set to false.
148 global
150 • Default: false
151 • Type: Boolean
153 Operates in "global" mode, so that packages are installed into the pre‐
156 fix folder instead of the current working directory. See npm help fold‐
157 ers for more on the differences in behavior.
158 • packages are installed into the {prefix}/lib/node_modules folder,
160 instead of the current working directory.
161 • bin files are linked to {prefix}/bin
163 • man pages are linked to {prefix}/share/man
165 install-strategy
168 • Default: "hoisted"
169 • Type: "hoisted", "nested", "shallow", or "linked"
171 Sets the strategy for installing packages in node_modules. hoisted (de‐
174 fault): Install non-duplicated in top-level, and duplicated as neces‐
175 sary within directory structure. nested: (formerly --legacy-bundling)
176 install in place, no hoisting. shallow (formerly --global-style) only
177 install direct deps at top-level. linked: (experimental) install in
178 node_modules/.store, link in place, unhoisted.
179 legacy-bundling
181 • Default: false
182 • Type: Boolean
184 • DEPRECATED: This option has been deprecated in favor of --install-
186 strategy=nested
187 Instead of hoisting package installs in node_modules, install packages
190 in the same manner that they are depended on. This may cause very deep
191 directory structures and duplicate package installs as there is no de-
192 duplicating. Sets --install-strategy=nested.
193 global-style
195 • Default: false
196 • Type: Boolean
198 • DEPRECATED: This option has been deprecated in favor of --install-
200 strategy=shallow
201 Only install direct dependencies in the top level node_modules, but
204 hoist on deeper dependencies. Sets --install-strategy=shallow.
205 omit
207 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
208 duction', otherwise empty.
209 • Type: "dev", "optional", or "peer" (can be set multiple times)
211 Dependency types to omit from the installation tree on disk.
214 Note that these dependencies are still resolved and added to the pack‐
216 age-lock.json or npm-shrinkwrap.json file. They are just not physically
217 installed on disk.
218 If a package type appears in both the --include and --omit lists, then
220 it will be included.
221 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
223 ment variable will be set to 'production' for all lifecycle scripts.
224 include
226 • Default:
227 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
229 times)
230 Option that allows for defining which types of dependencies to install.
233 This is the inverse of --omit=<type>.
235 Dependency types specified in --include will not be omitted, regardless
237 of the order in which omit/include are specified on the command-line.
238 strict-peer-deps
240 • Default: false
241 • Type: Boolean
243 If set to true, and --legacy-peer-deps is not set, then any conflicting
246 peerDependencies will be treated as an install failure, even if npm
247 could reasonably guess the appropriate resolution based on non-peer de‐
248 pendency relationships.
249 By default, conflicting peerDependencies deep in the dependency graph
251 will be resolved using the nearest non-peer dependency specification,
252 even if doing so will result in some packages receiving a peer depen‐
253 dency outside the range set in their package's peerDependencies object.
254 When such an override is performed, a warning is printed, explaining
256 the conflict and the packages involved. If --strict-peer-deps is set,
257 then this warning is treated as a failure.
258 package-lock
260 • Default: true
261 • Type: Boolean
263 If set to false, then ignore package-lock.json files when installing.
266 This will also prevent writing package-lock.json if save is true.
267 foreground-scripts
269 • Default: false
270 • Type: Boolean
272 Run all build scripts (ie, preinstall, install, and postinstall)
275 scripts for installed packages in the foreground process, sharing stan‐
276 dard input, output, and error with the main npm process.
277 Note that this will generally make installs run slower, and be much
279 noisier, but can be useful for debugging.
280 ignore-scripts
282 • Default: false
283 • Type: Boolean
285 If true, npm does not run scripts specified in package.json files.
288 Note that commands explicitly intended to run a particular script, such
290 as npm start, npm stop, npm restart, npm test, and npm run-script will
291 still run their intended script if ignore-scripts is set, but they will
292 not run any pre- or post-scripts.
293 audit
295 • Default: true
296 • Type: Boolean
298 When "true" submit audit reports alongside the current npm command to
301 the default registry and all registries configured for scopes. See the
302 documentation for npm help audit for details on what is submitted.
303 bin-links
305 • Default: true
306 • Type: Boolean
308 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
311 ecutables.
312 Set to false to have it not do this. This can be used to work around
314 the fact that some file systems don't support symlinks, even on osten‐
315 sibly Unix systems.
316 fund
318 • Default: true
319 • Type: Boolean
321 When "true" displays the message at the end of each npm install ac‐
324 knowledging the number of dependencies looking for funding. See npm
325 help fund for details.
326 dry-run
328 • Default: false
329 • Type: Boolean
331 Indicates that you don't want npm to make any changes and that it
334 should only report what it would have done. This can be passed into any
335 of the commands that modify your local installation, eg, install, up‐
336 date, dedupe, uninstall, as well as pack and publish.
337 Note: This is NOT honored by other network related commands, eg dist-
339 tags, owner, etc.
340 workspace
342 • Default:
343 • Type: String (can be set multiple times)
345 Enable running a command in the context of the configured workspaces of
348 the current project while filtering by running only the workspaces de‐
349 fined by this configuration option.
350 Valid values for the workspace config are either:
352 • Workspace names
354 • Path to a workspace directory
356 • Path to a parent workspace directory (will result in selecting all
358 workspaces within that folder)
359 When set for the npm init command, this may be set to the folder of a
362 workspace which does not yet exist, to create the folder and set it up
363 as a brand new workspace within the project.
364 This value is not exported to the environment for child processes.
366 workspaces
368 • Default: null
369 • Type: null or Boolean
371 Set to true to run the command in the context of all configured
374 workspaces.
375 Explicitly setting this to false will cause commands like install to
377 ignore workspaces altogether. When not set explicitly:
378 • Commands that operate on the node_modules tree (install, update,
380 etc.) will link workspaces into the node_modules folder. - Commands
381 that do other things (test, exec, publish, etc.) will operate on
382 the root project, unless one or more workspaces are specified in
383 the workspace config.
384 This value is not exported to the environment for child processes.
387 include-workspace-root
389 • Default: false
390 • Type: Boolean
392 Include the workspace root when workspaces are enabled for a command.
395 When false, specifying individual workspaces via the workspace config,
397 or all workspaces via the workspaces flag, will cause npm to operate
398 only on the specified workspaces, and not on the root project.
399 This value is not exported to the environment for child processes.
401 install-links
403 • Default: false
404 • Type: Boolean
406 When set file: protocol dependencies will be packed and installed as
409 regular dependencies instead of creating a symlink. This option has no
410 effect on workspaces.
411 See Also
413 • npm help install
414 • npm help outdated
416 • npm help shrinkwrap
418 • npm help registry
420 • npm help folders
422 • npm help ls
424 November 2023 NPM-UPDATE(1)