NPM-UPDATE(1)

📦

version 12.2.1 · 30 versions

💅 NPM-UPDATE(1) — like, the official glow-up guide 🌸

okay bestie so this is npm-update from the NPM-UPDATE(1) manual and honestly? it's giving "your deps are dusty, let's fix that" energy. sit down, grab a strawberry drink 🍓, and let's go.

✨ NAME ✨

npm-update — the command that updates your packages. that's it, that's the whole vibe. 💖

🦋 Synopsis

npm update [<pkg>...]

aliases: u, up, upgrade, udpate

yes queen, udpate is a real alias. it's a typo that got canonized. we respect it. iykyk. 🙈

🌈 DESCRIPTION 🌈

okay so listen 💅 — this command updates all the packages you list up to the latest version (the version specified by the tag config ⟨/using-npm/config#tag⟩), and it respects the semver constraints of both your package and its dependencies (if those deps also want the same package). it's very polite like that. 🎀

it will also install missing packages. like if something's just... not there? it shows up. main character behavior honestly. 👑

if the -g flag is specified, this command will update globally installed packages. global mode, global queen. 🌍💖

if no package name is specified, all packages in the specified location (global or local) get updated. the whole fit gets refreshed. ✨

big note bestie 🫶 — by default npm update will not update the semver values of direct dependencies in your project package.json. if you want to also update values in package.json you can run npm update --save (or add the save=true option to a npm help "configuration file" to make that the default behavior). like, you gotta ask for that.

🧚 EXAMPLE 🧚

for the examples below, assume that the current package is app and it depends on dependencies, dep1 (dep2, .. etc.). the published versions of dep1 are:

{
  "dist-tags": { "latest": "1.2.2" },
  "versions": [
    "1.2.2",
    "1.2.1",
    "1.2.0",
    "1.1.2",
    "1.1.1",
    "1.0.0",
    "0.4.1",
    "0.4.0",
    "0.2.0"
  ]
}

keep that list in your head, girl, we're about to use it a lot. 💀

⭐ Caret Dependencies

if app's package.json contains:

"dependencies": {
  "dep1": "^1.1.1"
}

then npm update will install dep1@1.2.2, because 1.2.2 is latest and 1.2.2 satisfies ^1.1.1. slay, no notes. 💅

🌸 Tilde Dependencies

however, if app's package.json contains:

"dependencies": {
  "dep1": "~1.1.1"
}

in this case, running npm update will install dep1@1.1.2. even though the latest tag points to 1.2.2, this version does not satisfy ~1.1.1, which is equivalent to >=1.1.1 <1.2.0. so the highest-sorting version that satisfies ~1.1.1 is used, which is 1.1.2. the tilde said "boundaries, bestie" and npm respected them. 🫶

🎀 Caret Dependencies below 1.0.0

suppose app has a caret dependency on a version below 1.0.0, for example:

"dependencies": {
  "dep1": "^0.2.0"
}

npm update will install dep1@0.2.0.

if the dependence were on ^0.4.0:

"dependencies": {
  "dep1": "^0.4.0"
}

then npm update will install dep1@0.4.1, because that is the highest-sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0). the pre-1.0 caret is a whole different creature and it ate. 🔥

🦋 Subdependencies

suppose your app now also has a dependency on dep2

{
  "name": "my-app",
  "dependencies": {
      "dep1": "^1.0.0",
      "dep2": "1.0.0"
  }
}

and dep2 itself depends on this limited range of dep1

{
"name": "dep2",
  "dependencies": {
    "dep1": "~1.1.1"
  }
}

then npm update will install dep1@1.1.2 because that is the highest version that dep2 allows. npm will prioritize having a single version of dep1 in your tree rather than two when that single version can satisfy the semver requirements of multiple dependencies in your tree. one version, one outfit, no duplicates. 👑

in this case if you really did need your package to use a newer version you would need to use npm install. that's the whole tea. ☕

💜 Updating Globally-Installed Packages

npm update -g will apply the update action to each globally installed package that is outdated — that is, has a version that is different from wanted.

note: 📌 globally installed packages do not have a package.json semver range available, so their wanted version is latest.

NOTE: 💀 if a package has been upgraded to a version newer than latest, it will be downgraded. yes, for real. it's not a bug, it's the documented behavior, and it is dramatic.

🛠️ Configuration 🛠️

okay this is the long part, bestie, stay with me. every single option, no skipping. 💖

💾 save

Default: true unless when using npm update where it defaults to false
Type: Boolean

save installed packages to a package.json file as dependencies.

when used with the npm rm command, removes the dependency from package.json.

will also prevent writing to package-lock.json if set to false. so false is like "i don't want receipts." 🧾🙈

🌍 global

Default: false
Type: Boolean

operates in "global" mode, so that packages are installed into the prefix folder instead of the current working directory. see npm help folders for more on the differences in behavior.

packages are installed into the {prefix}/lib/node_modules folder, instead of the current working directory.
bin files are linked to {prefix}/bin
man pages are linked to {prefix}/share/man

the whole system gets the glow-up, not just your folder. 🌈

🧱 install-strategy

Default: "hoisted"
Type: "hoisted", "nested", "shallow", or "linked"

sets the strategy for installing packages in node_modules. let's break it down:

hoisted (default): install non-duplicated in top-level, and duplicated as necessary within directory structure.
nested: (formerly --legacy-bundling) install in place, no hoisting.
shallow: (formerly --global-style) only install direct deps at top-level.
linked: install in node_modules/.store, link in place, unhoisted.

we recommend that package authors use --install-strategy=linked during development to catch undeclared ("phantom") dependencies before publishing: the isolated layout only exposes a package's declared dependencies, so an import of a package that was never added to package.json can fail instead of resolving by accident and shipping broken. see Catching undeclared ("phantom") dependencies ⟨/using-npm/developers#catching-undeclared-phantom-dependencies⟩. phantom deps are literally the ghosts of bad imports past 👻 and you do NOT want them haunting your publish.

🎗️ legacy-bundling

Default: false
Type: Boolean
DEPRECATED: this option has been deprecated in favor of --install-strategy=nested

instead of hoisting package installs in node_modules, install packages in the same manner that they are depended on. this may cause very deep directory structures and duplicate package installs as there is no de-duplicating. sets --install-strategy=nested. it's giving "folder inception" 😭 — use the new flag.

🕰️ global-style

Default: false
Type: Boolean
DEPRECATED: this option has been deprecated in favor of --install-strategy=shallow

only install direct dependencies in the top level node_modules, but hoist on deeper dependencies. sets --install-strategy=shallow. also deprecated, also still documented, also please use the new one bestie. 🫶

🚫 omit

Default: 'dev' if the NODE_ENV environment variable is set to 'production'; otherwise, empty.
Type: "dev", "optional", or "peer" (can be set multiple times)

dependency types to omit from the installation tree on disk.

important 📌 — note that these dependencies are still resolved and added to the package-lock.json file. they are just not physically installed on disk. they're invited to the group chat but they don't show up to the party.

if a package type appears in both the --include and --omit lists, then it will be included. inclusion wins, always.

if the resulting omit list includes 'dev', then the NODE_ENV environment variable will be set to 'production' for all lifecycle scripts.

🎁 include

Default: (empty)
Type: "prod", "dev", "optional", or "peer" (can be set multiple times)

option that allows for defining which types of dependencies to install.

this is the inverse of --omit=<type>.

dependency types specified in --include will not be omitted, regardless of the order in which omit/include are specified on the command-line. order doesn't matter, include just wins. 👑

🔒 strict-peer-deps

Default: false
Type: Boolean

if set to true, and --legacy-peer-deps is not set, then any conflicting peerDependencies will be treated as an install failure, even if npm could reasonably guess the appropriate resolution based on non-peer dependency relationships. no vibes-based guessing allowed, we're being strict. 💅

by default, conflicting peerDependencies deep in the dependency graph will be resolved using the nearest non-peer dependency specification, even if doing so will result in some packages receiving a peer dependency outside the range set in their package's peerDependencies object.

when such an override is performed, a warning is printed, explaining the conflict and the packages involved. if --strict-peer-deps is set, then this warning is treated as a failure. so like, the warning becomes the whole problem. 😭

📜 package-lock

Default: true
Type: Boolean

if set to false, then ignore package-lock.json files when installing. this will also prevent writing package-lock.json if save is true. chaotic, but documented. 💀

🎤 foreground-scripts

Default: false unless when using npm pack or npm publish where it defaults to true
Type: Boolean

run all build scripts (ie, preinstall, install, and postinstall) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

note 📢 — this will generally make installs run slower, and be much noisier, but can be useful for debugging. it's the "turn the mic all the way up" option.

🙈 ignore-scripts

Default: false
Type: Boolean

if true, npm does not run scripts specified in package.json files.

note that commands explicitly intended to run a particular script, such as npm start, npm stop, npm restart, npm test, and npm run will still run their intended script if ignore-scripts is set, but they will not run any pre- or post-scripts. the main event still happens, the opening act is cancelled. 🎬

setting ignore-scripts also disables .npm-extension execution, as if ignore-extension were set.

✅ allow-scripts

Default: ""
Type: String (can be set multiple times)

comma-separated list of packages whose install-time lifecycle scripts (preinstall, install, postinstall, and prepare for non-registry dependencies) are allowed to run. an approved-guest list, basically. 🎟️

this setting is intended for one-off and global contexts: npm exec, npx, and npm install -g, where no project package.json is involved. for team-wide policy in a project, use the allowScripts field in package.json (which also supports explicit denials), or configure it in .npmrc.

warning ⚠️ — passing --allow-scripts on the command line during a project-scoped npm install, ci, update, or rebuild is an error. not a warning, an error. do not.

each name is matched against a dependency's resolved identity, not against the package's self-reported name. --ignore-scripts and --dangerously-allow-all-scripts both override this setting.

this value is not exported to the environment for child processes.

🧷 strict-allow-scripts

Default: false
Type: Boolean

if true, turn the install-script policy from a warning into a hard error: any dependency with install scripts that is not covered by allowScripts will fail the install instead of being blocked with a warning. it's giving "no uninvited guests, and i mean it." 🚪

dependencies explicitly denied with false in allowScripts are always silently skipped; this setting only affects unreviewed entries (packages with install scripts that are neither approved nor denied). --ignore-scripts and --dangerously-allow-all-scripts both override this setting.

optional dependencies that cannot be installed on the current platform or engine (a non-matching os, cpu, or libc) are not flagged, because their install scripts never run. so they're not skipping the party, they just literally can't get in. 🫶

💀 dangerously-allow-all-scripts

Default: false
Type: Boolean

(to be continued, bestie — part 2 is coming and we are NOT done yet 🦋✨)

okay so if this one is <code>true</code>, it literally bypasses the allowScripts policy entirely and runs every single dependency install script — no vibe check, no approval needed, doesn't matter whether it was approved or denied. It's a migration escape hatch and only that, and using it is strongly discouraged 🚩. Also <code>--ignore-scripts</code> still takes precedence over this setting, so that one always wins, periodt.

🍓 audit

Default: true
Type: Boolean

When it's "true", npm submits audit reports alongside whatever npm command you just ran — to the default registry and to all the registries configured for scopes. Slay. See npm help audit for the deets on exactly what gets sent 💅

🦋 before

Default: null
Type: null or Date

Bestie, if you pass this to npm install, npm rebuilds the whole tree so that only versions that were available on or before the given date get installed. And if there are, like, no versions available for your current set of dependencies? The command just errors out 😭

If the version you asked for is a dist-tag and that tag doesn't pass the --before filter, then the most recent version less than or equal to that tag gets used instead. Example: foo@latest might install foo@1.2 even though latest is 2.0. Not me getting downgraded 🫠

If before and min-release-age are both set in the same source, before wins (an explicit absolute date overrides a relative window). Across sources, the standard precedence applies (cli > env > project > user > global), so a higher-priority source can always relax or override a lower-priority one. iykyk.

And same energy as min-release-age: when this cutoff blocks a fix that npm audit fix would install, npm keeps the vulnerable version, warns you, and exits with a non-zero code 💀

Packages whose names match min-release-age-exclude are exempt from this filter.

🎀 min-release-age

Default: null
Type: null or Number

If you set this, npm builds the tree so that only versions that were available more than the given number of days ago will be installed. No versions available for your current deps? Command errors. Simple as that ✨

This flag is the complement to before — before takes an exact date, this takes a relative number of days. They can coexist (for example, min-release-age in your .npmrc is preserved when npm internally spawns a sub-process with --before while preparing a git: or github: dependency). When both apply, before wins within a single source, and across sources the standard precedence rules apply 👑

When this window stops npm audit fix from installing a patched version (because the fix was published too recently, tragic), npm keeps the package at its vulnerable version, warns that the fix was blocked, and exits with a non-zero code. To actually install the fix, add the package to min-release-age-exclude, or relax min-release-age or before. 🙈

Packages whose names match min-release-age-exclude are exempt from this filter.

This value is not exported to the environment for child processes.

🌸 min-release-age-exclude

Default:
Type: String (can be set multiple times)

A list of package names or minimatch glob patterns that are exempt from the min-release-age (and before) filter. A matching package can always resolve to its newest version, even when a release-age window is set. Main character behaviour, honestly 👑

For example, to apply a release-age window to third-party dependencies while letting internally maintained packages update immediately:

min-release-age=7
min-release-age-exclude[]=@myorg/*
min-release-age-exclude[]=my-internal-pkg

Only the named package is exempt — its own dependencies still follow the release-age policy unless they also match a pattern. Patterns match against the package name, so @myorg/* matches @myorg/shared-utils 🧚

Excluding a package does not change which registry it is fetched from. And fr fr, you should own your private scope on the public registry so that nobody else can publish a package with the same name. Protect your name, bestie 🛡️

This value is not exported to the environment for child processes.

💜 bin-links

Default: true
Type: Boolean

Tells npm to create symlinks (or .cmd shims on Windows) for package executables ✨

Set it to false and npm won't do that. Handy workaround for the fact that some file systems just don't support symlinks — even on ostensibly Unix systems, which is giving chaos 😭

🌈 fund

Default: true
Type: Boolean

When "true", it displays the message at the end of each npm install acknowledging the number of dependencies looking for funding. Support the ecosystem, bestie 🫶 See npm help fund for details.

⭐ dry-run

Default: false
Type: Boolean

Indicates that you don't want npm to make any changes and that it should only report what it would have done. You can pass this into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall, as well as pack and publish. A little preview era ✨

Note: this is NOT honored by other network related commands, eg dist-tags, owner, etc. So don't be surprised when those still do the thing 💀

🎀 workspace

Default:
Type: String (can be set multiple times)

Enables running a command in the context of the configured workspaces of the current project, while filtering by running only the workspaces defined by this config option.

Valid values for the workspace config are either:

Workspace names
Path to a workspace directory
Path to a parent workspace directory (will result in selecting all workspaces within that folder)

When set for the npm init command, this may be set to the folder of a workspace which does not yet exist, so npm can create the folder and set it up as a brand new workspace within the project. New workspace just dropped 💅

This value is not exported to the environment for child processes.

🦋 workspaces

Default: null
Type: null or Boolean

Set to true to run the command in the context of all configured workspaces.

Explicitly setting this to false will cause commands like install to ignore workspaces altogether. When not set explicitly:

Commands that operate on the node_modules tree (install, update, etc.) will link workspaces into the node_modules folder.
Commands that do other things (test, exec, publish, etc.) will operate on the root project, unless one or more workspaces are specified in the workspace config.

This value is not exported to the environment for child processes.

🧚 include-workspace-root

Default: false
Type: Boolean

Include the workspace root when workspaces are enabled for a command.

When false, specifying individual workspaces via the workspace config, or all workspaces via the workspaces flag, will cause npm to operate only on the specified workspaces — not on the root project. Root project said "not invited to the group chat" 😭

This value is not exported to the environment for child processes.

💖 install-links

Default: false
Type: Boolean

When set, file: protocol dependencies will be packed and installed as regular dependencies instead of creating a symlink. No symlink, just vibes 📦

This option has no effect on workspaces.

👀 See Also

npm help install
npm help outdated
npm help registry
npm help folders
npm help ls

And that's the whole page, bestie — you ate that 🫶 This lil beauty is from NPM@12.2.1, dated October 2026, and it's the NPM-UPDATE(1) manual page. Go update something iconic 💅✨

📦 where this page comes from

arch rolling: npm 12.2.1-1 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms