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), respecting the semver constraints of
16 both your package and its dependencies (if they also require the same
17 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 the
31 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 high‐
93 est-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 false
137 • Type: Boolean
139 Save installed packages to a package.json file as dependencies.
142 When used with the npm rm command, removes the dependency from pack‐
144 age.json.
145 Will also prevent writing to package-lock.json if set to false.
147 global
149 • Default: false
150 • Type: Boolean
152 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 • packages are installed into the {prefix}/lib/node_modules folder, in‐
159 stead of the current working directory.
160 • bin files are linked to {prefix}/bin
162 • man pages are linked to {prefix}/share/man
164 global-style
167 • Default: false
168 • Type: Boolean
170 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 legacy-bundling
180 • Default: false
181 • Type: Boolean
183 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 omit
191 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
192 duction', otherwise empty.
193 • Type: "dev", "optional", or "peer" (can be set multiple times)
195 Dependency types to omit from the installation tree on disk.
198 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 If a package type appears in both the --include and --omit lists, then
204 it will be included.
205 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 strict-peer-deps
210 • Default: false
211 • Type: Boolean
213 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 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 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 package-lock
230 • Default: true
231 • Type: Boolean
233 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 This configuration does not affect npm ci.
239 foreground-scripts
241 • Default: false
242 • Type: Boolean
244 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 Note that this will generally make installs run slower, and be much
251 noisier, but can be useful for debugging.
252 ignore-scripts
254 • Default: false
255 • Type: Boolean
257 If true, npm does not run scripts specified in package.json files.
260 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 audit
267 • Default: true
268 • Type: Boolean
270 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 bin-links
277 • Default: true
278 • Type: Boolean
280 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
283 ecutables.
284 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 fund
290 • Default: true
291 • Type: Boolean
293 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 dry-run
300 • Default: false
301 • Type: Boolean
303 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 Note: This is NOT honored by other network related commands, eg
311 dist-tags, owner, etc.
312 workspace
314 • Default:
315 • Type: String (can be set multiple times)
317 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 Valid values for the workspace config are either:
324 • Workspace names
326 • Path to a workspace directory
328 • Path to a parent workspace directory (will result in selecting all
330 workspaces within that folder)
331 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 This value is not exported to the environment for child processes.
338 workspaces
340 • Default: null
341 • Type: null or Boolean
343 Set to true to run the command in the context of all configured
346 workspaces.
347 Explicitly setting this to false will cause commands like install to
349 ignore workspaces altogether. When not set explicitly:
350 • 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 This value is not exported to the environment for child processes.
359 include-workspace-root
361 • Default: false
362 • Type: Boolean
364 Include the workspace root when workspaces are enabled for a command.
367 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 This value is not exported to the environment for child processes.
373 install-links
375 • Default: false
376 • Type: Boolean
378 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 See Also
385 • npm help install
386 • npm help outdated
388 • npm help shrinkwrap
390 • npm help registry
392 • npm help folders
394 • npm help ls
396 September 2022 NPM-UPDATE(1)