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.