1NPM-UPDATE(1) NPM-UPDATE(1)
2
3
4
6 npm-update - Update packages
7
8 Synopsis
9 npm update [<pkg>...]
10
11 aliases: up, upgrade, udpate
12
13 Description
14 This command will update all the packages listed to the latest version
15 (specified by the tag config), respecting the semver constraints of
16 both your package and its dependencies (if they also require the same
17 package).
18
19 It will also install missing packages.
20
21 If the -g flag is specified, this command will update globally in‐
22 stalled packages.
23
24 If no package name is specified, all packages in the specified location
25 (global or local) will be updated.
26
27 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 the
31 default behavior).
32
33 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
38 {
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
53 Caret Dependencies
54 If app's package.json contains:
55
56 "dependencies": {
57 "dep1": "^1.1.1"
58 }
59
60 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
63 Tilde Dependencies
64 However, if app's package.json contains:
65
66 "dependencies": {
67 "dep1": "~1.1.1"
68 }
69
70 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
75 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
79 "dependencies": {
80 "dep1": "^0.2.0"
81 }
82
83 npm update will install dep1@0.2.0, because there are no other versions
84 which satisfy ^0.2.0.
85
86 If the dependence were on ^0.4.0:
87
88 "dependencies": {
89 "dep1": "^0.4.0"
90 }
91
92 Then npm update will install dep1@0.4.1, because that is the high‐
93 est-sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0)
94
95 Subdependencies
96 Suppose your app now also has a dependency on dep2
97
98 {
99 "name": "my-app",
100 "dependencies": {
101 "dep1": "^1.0.0",
102 "dep2": "1.0.0"
103 }
104 }
105
106 and dep2 itself depends on this limited range of dep1
107
108 {
109 "name": "dep2",
110 "dependencies": {
111 "dep1": "~1.1.1"
112 }
113 }
114
115 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
122 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
127 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
131 NOTE: If a package has been upgraded to a version newer than latest, it
132 will be downgraded.
133
134 Configuration
135 save
136 • Default: true unless when using npm update where it defaults to false
137
138 • Type: Boolean
139
140
141 Save installed packages to a package.json file as dependencies.
142
143 When used with the npm rm command, removes the dependency from pack‐
144 age.json.
145
146 Will also prevent writing to package-lock.json if set to false.
147
148 global
149 • Default: false
150
151 • Type: Boolean
152
153
154 Operates in "global" mode, so that packages are installed into the pre‐
155 fix folder instead of the current working directory. See npm help fold‐
156 ers for more on the differences in behavior.
157
158 • packages are installed into the {prefix}/lib/node_modules folder, in‐
159 stead of the current working directory.
160
161 • bin files are linked to {prefix}/bin
162
163 • man pages are linked to {prefix}/share/man
164
165
166 global-style
167 • Default: false
168
169 • Type: Boolean
170
171
172 Causes npm to install the package into your local node_modules folder
173 with the same layout it uses with the global node_modules folder. Only
174 your direct dependencies will show in node_modules and everything they
175 depend on will be flattened in their node_modules folders. This obvi‐
176 ously will eliminate some deduping. If used with legacy-bundling,
177 legacy-bundling will be preferred.
178
179 legacy-bundling
180 • Default: false
181
182 • Type: Boolean
183
184
185 Causes npm to install the package such that versions of npm prior to
186 1.4, such as the one included with node 0.8, can install the package.
187 This eliminates all automatic deduping. If used with global-style this
188 option will be preferred.
189
190 omit
191 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
192 duction', otherwise empty.
193
194 • Type: "dev", "optional", or "peer" (can be set multiple times)
195
196
197 Dependency types to omit from the installation tree on disk.
198
199 Note that these dependencies are still resolved and added to the pack‐
200 age-lock.json or npm-shrinkwrap.json file. They are just not physically
201 installed on disk.
202
203 If a package type appears in both the --include and --omit lists, then
204 it will be included.
205
206 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
207 ment variable will be set to 'production' for all lifecycle scripts.
208
209 strict-peer-deps
210 • Default: false
211
212 • Type: Boolean
213
214
215 If set to true, and --legacy-peer-deps is not set, then any conflicting
216 peerDependencies will be treated as an install failure, even if npm
217 could reasonably guess the appropriate resolution based on non-peer de‐
218 pendency relationships.
219
220 By default, conflicting peerDependencies deep in the dependency graph
221 will be resolved using the nearest non-peer dependency specification,
222 even if doing so will result in some packages receiving a peer depen‐
223 dency outside the range set in their package's peerDependencies object.
224
225 When such and override is performed, a warning is printed, explaining
226 the conflict and the packages involved. If --strict-peer-deps is set,
227 then this warning is treated as a failure.
228
229 package-lock
230 • Default: true
231
232 • Type: Boolean
233
234
235 If set to false, then ignore package-lock.json files when installing.
236 This will also prevent writing package-lock.json if save is true.
237
238 This configuration does not affect npm ci.
239
240 foreground-scripts
241 • Default: false
242
243 • Type: Boolean
244
245
246 Run all build scripts (ie, preinstall, install, and postinstall)
247 scripts for installed packages in the foreground process, sharing stan‐
248 dard input, output, and error with the main npm process.
249
250 Note that this will generally make installs run slower, and be much
251 noisier, but can be useful for debugging.
252
253 ignore-scripts
254 • Default: false
255
256 • Type: Boolean
257
258
259 If true, npm does not run scripts specified in package.json files.
260
261 Note that commands explicitly intended to run a particular script, such
262 as npm start, npm stop, npm restart, npm test, and npm run-script will
263 still run their intended script if ignore-scripts is set, but they will
264 not run any pre- or post-scripts.
265
266 audit
267 • Default: true
268
269 • Type: Boolean
270
271
272 When "true" submit audit reports alongside the current npm command to
273 the default registry and all registries configured for scopes. See the
274 documentation for npm help audit for details on what is submitted.
275
276 bin-links
277 • Default: true
278
279 • Type: Boolean
280
281
282 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
283 ecutables.
284
285 Set to false to have it not do this. This can be used to work around
286 the fact that some file systems don't support symlinks, even on osten‐
287 sibly Unix systems.
288
289 fund
290 • Default: true
291
292 • Type: Boolean
293
294
295 When "true" displays the message at the end of each npm install ac‐
296 knowledging the number of dependencies looking for funding. See npm
297 help npm fund for details.
298
299 dry-run
300 • Default: false
301
302 • Type: Boolean
303
304
305 Indicates that you don't want npm to make any changes and that it
306 should only report what it would have done. This can be passed into any
307 of the commands that modify your local installation, eg, install, up‐
308 date, dedupe, uninstall, as well as pack and publish.
309
310 Note: This is NOT honored by other network related commands, eg
311 dist-tags, owner, etc.
312
313 workspace
314 • Default:
315
316 • Type: String (can be set multiple times)
317
318
319 Enable running a command in the context of the configured workspaces of
320 the current project while filtering by running only the workspaces de‐
321 fined by this configuration option.
322
323 Valid values for the workspace config are either:
324
325 • Workspace names
326
327 • Path to a workspace directory
328
329 • Path to a parent workspace directory (will result in selecting all
330 workspaces within that folder)
331
332
333 When set for the npm init command, this may be set to the folder of a
334 workspace which does not yet exist, to create the folder and set it up
335 as a brand new workspace within the project.
336
337 This value is not exported to the environment for child processes.
338
339 workspaces
340 • Default: null
341
342 • Type: null or Boolean
343
344
345 Set to true to run the command in the context of all configured
346 workspaces.
347
348 Explicitly setting this to false will cause commands like install to
349 ignore workspaces altogether. When not set explicitly:
350
351 • Commands that operate on the node_modules tree (install, update,
352 etc.) will link workspaces into the node_modules folder. - Commands
353 that do other things (test, exec, publish, etc.) will operate on the
354 root project, unless one or more workspaces are specified in the
355 workspace config.
356
357
358 This value is not exported to the environment for child processes.
359
360 include-workspace-root
361 • Default: false
362
363 • Type: Boolean
364
365
366 Include the workspace root when workspaces are enabled for a command.
367
368 When false, specifying individual workspaces via the workspace config,
369 or all workspaces via the workspaces flag, will cause npm to operate
370 only on the specified workspaces, and not on the root project.
371
372 This value is not exported to the environment for child processes.
373
374 install-links
375 • Default: false
376
377 • Type: Boolean
378
379
380 When set file: protocol dependencies that exist outside of the project
381 root will be packed and installed as regular dependencies instead of
382 creating a symlink. This option has no effect on workspaces.
383
384 See Also
385 • npm help install
386
387 • npm help outdated
388
389 • npm help shrinkwrap
390
391 • npm help registry
392
393 • npm help folders
394
395 • npm help ls
396
397
398
399
400 September 2022 NPM-UPDATE(1)