Node npm

ID

npm

Home page

https://www.npmjs.com

Version requirement

>= 11.10

Cooldown

✓

Platforms

🅱️ BSD · 🐧 Linux · 🍎 macOS · ⨂ Unix · 🪟 Windows

Operations

installed · outdated · search · install · upgrade · upgrade_all · remove · cleanup · doctor

purl types

pkg:npm

Brewfile entry

npm, in Brewfile backups

CLI name

npm

Every call

npm --global --no-progress --no-update-notifier --no-fund --no-audit <command>

Issues and PRs

📦 manager: npm-based

Source

meta_package_manager/managers/npm.py

The Node.js package manager.

mpm drives npm in global mode: every call forces --global so packages land in the shared prefix instead of the current working directory. Per-scope targeting and multi-binary discovery (several node versions through nvm) are tracked in #1725. Command equivalences with the sibling JS managers are listed in antfu-collective/ni.

Queries parse npm’s --json output. Mutating operations are marked privileged so --sudo can escalate writes into a root-owned global prefix, though escalation stays dormant unless requested.

Note

npm enforces a supply-chain cooldown through its min-release-age resolver option, refusing to resolve any release younger than the configured age. The version floor exists for it: min-release-age first shipped in 11.10.0, and older releases silently ignore the setting.

Caution

A fatal npm error (usually a local node version out of sync) is reported both on <stderr> and as a JSON blob on <stdout>. The run_cli override blanks that JSON so the failure surfaces once, through <stderr>, rather than being parsed as a package listing.

What mpm adds to npm

Through mpm, npm gains --exact search, to narrow results to exact names.

Bigger still, mpm reaches across every manager at once: mpm installed and mpm outdated cover npm alongside pnpm, volta, yarn, yarn-berry and any other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Your npm commands, in mpm

You already know npm: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…	With npm	With mpm
List what’s installed	npm --json --depth 0 list	mpm --npm installed
List outdated packages	npm --json outdated	mpm --npm outdated
Search for a package	npm search --json python	mpm --npm search python
Install a package	npm install markdown	mpm install pkg:npm/markdown
Upgrade one package	npm upgrade raven	mpm --npm upgrade raven
Upgrade everything	npm update	mpm --npm upgrade --all
Remove a package	npm uninstall raven	mpm remove pkg:npm/raven
Clear caches	npm cache clean --force	mpm --npm cleanup --cache
Run health checks	npm doctor	mpm --npm doctor

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations

Operation	Supported	Notes
installed	✓
outdated	✓
orphans
search	✓	exact search backfilled by mpm
install	✓
upgrade	✓
upgrade_all	✓
remove	✓
sync
cleanup	✓
doctor	✓

Selecting and configuring npm

Deselect npm for a single run with --no-npm, or persist the choice in your configuration:

[mpm]
npm = false

The arguments and environment variables listed in the box atop this page are forced on every npm call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.managers.npm]
timeout = 900

mpm config-template npm prints every overridable attribute as a ready-to-paste block.

Recipes

A few jobs you would otherwise script around npm, one mpm command each:

• Snapshot and clone a machine: mpm --npm dump npm.toml, then mpm restore npm.toml on the next one.

• Export a Brewfile entry instead: mpm --npm dump --brewfile Brewfile.

• Export a compliance SBOM: mpm --npm sbom (CycloneDX by default, --spdx for SPDX).

• Gate CI on health: mpm --npm doctor relays Node npm’s own diagnosis and exits non-zero on trouble.

Privilege escalation

mpm runs this manager as the current user and never prepends sudo by default. Flip the policy for its privileged operations with --sudo or the per-manager sudo override.

See privilege escalation for the full policy.

Cooldown

mpm natively enforces its release-age cooldown on Node npm, injecting the npm_config_min-release-age environment variable on every call. Point it at a window (mpm --cooldown 7 --npm upgrade --all) to skip anything published in the last 7 days: a guard against a compromised or yanked fresh release landing before anyone notices.

• Status: ✅ Enforced (npm ≥ 11.10)

• Mechanism: min-release-age env npm_config_min-release-age (integer days)

• Reference: npm docs

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

• Registry: npm registry (pkg:npm)

• Retraction: Unpublish within 72 h of publishing, then only with no dependents, under 300 weekly downloads and a single owner (policy). Past that, flag only: npm deprecate warns on install but does not stop resolution

• Publish date: ✅ time, mapping each version to its publication timestamp (packument)

Version probe

The version is extracted from the output of npm --version with:

r"(?P<version>\S+)"

Reference traces

Raw native outputs captured in the manager source: the reference mpm’s parsers were written against. If you know Node npm well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ npm --global --no-progress --no-update-notifier --no-fund --no-audit             --json --depth 0 list
{
  "name": "lib",
  "dependencies": {
    "@eslint/json": {
      "version": "0.9.0",
      "overridden": false
    },
    "@mermaid-js/mermaid-cli": {
      "version": "10.8.0",
      "overridden": false
    },
    "corepack": {
      "version": "0.30.0",
      "overridden": false
    },
    "google-closure-compiler": {
      "version": "20240317.0.0",
      "overridden": false
    },
    "npm": {
      "version": "10.9.2",
      "overridden": false
    },
    "raven": {
      "version": "2.6.4",
      "overridden": false
    },
    "wrangler": {
      "version": "3.51.2",
      "overridden": false
    }
  }
}

$ npm --global --no-progress --no-update-notifier --no-fund --no-audit             --json outdated
{
  "my-linked-package": {
    "current": "0.0.0-development",
    "wanted": "linked",
    "latest": "linked",
    "location": "/Users/kev/dev/my-linked-package"
  },
  "npm": {
    "current": "3.10.3",
    "wanted": "3.10.5",
    "latest": "3.10.5",
    "location": "/opt/homebrew/lib/node_modules/npm"
  }
}

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --npm installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog

• 7.1.0 (2026-07-07)

  • install no longer passes --no-fund and --no-audit twice.

• 6.4.0 (2026-04-27)

  • Add cleanup operation.

• 6.2.1 (2026-03-26)

  • Fix crash on installed when no global packages are present. Closes #1603.

• 5.21.0 (2025-05-29)

  • Fix retrieval of installed packages.

• 5.5.1 (2022-07-11)

  • Implements remove operation.

  • Use canonical commands for operations.

  • Reduce output verbosity with --no-fund and --no-audit options.

• 5.3.0 (2022-06-25)

  • Apply global variables to all operations.

• 3.5.0 (2020-09-20)

  • Always fix JSON parsing on error for any npm subcommand.

• 3.4.2 (2020-09-13)

  • Skip parsing of JSON results on error.

• 3.0.0 (2020-03-25)

  • install package@version instead of update package.

  • Skip update notifier.

• 2.5.0 (2017-03-01)

  • Bump minimal requirement of npm to 4.0.*.

  • Allow use of apm, gem and npm managers on Linux.

• 1.4.0 (2016-07-10)

  • Check for linked npm packages.

• 1.2.0 (2016-07-08)

  • Add support for both pip2 and pip3, Node’s npm, Atom’s apm, Ruby’s gem.