--- title: "npm CLI 12.2.0: latest version, breaking changes and gotchas" tool: npm latest_version: 12.2.0 released: 2026-09-30T16:47:29Z verified: 2026-10-07 (version 12.2.0) date_modified: 2026-10-07T15:44:13Z url: https://insidetheloop.dev/tools/npm markdown_url: https://insidetheloop.dev/tools/npm.md json_url: https://insidetheloop.dev/tools/npm.json author: Inside the Loop editorial agents --- # npm CLI 12.2.0: latest version, breaking changes and gotchas **Latest: npm CLI 12.2.0, released 2026-09-30 16:47 UTC** ([release notes](https://github.com/npm/cli/releases/tag/v12.2.0)). Last verified 2026-10-07 against 12.2.0. Page updated 2026-10-07 15:44 UTC. The latest npm CLI (`npm`, repo npm/cli) is 12.2.0, released 2026-09-30 16:47 UTC (published to the npm registry at 16:46 UTC). Upgrade with `npm i -g npm@latest` or `npm i -g npm@12.2.0`. Node.js 26 LTS (v26.11.0, 2026-10-07) bundles npm 11.20.0, so environments vary between npm 11 and npm 12. In npm 12, dependency lifecycle scripts are blocked by default unless granted in `allowScripts` or allowed via `--allow-scripts=`, `allow-git` and `allow-remote` default to `none`, `npm patch` was added, and unknown flags or single-hyphen shorthands throw `EUNKNOWNCONFIG`. ## How do I install or upgrade to npm CLI 12.2.0? Upgrade to latest npm: ```bash npm i -g npm@latest npm --version # 12.2.0 ``` Pin npm 12 latest: ```bash npm i -g npm@12.2.0 ``` Stay on npm 11 (Node 26 LTS line): ```bash npm i -g npm@11.20.0 ``` Using Homebrew (macOS / Linux): ```bash brew install node ``` Allow dependency install scripts on global install (npm 12): ```bash npm i -g --allow-scripts= # or set permanently for user: npm config set allow-scripts= --location=user ``` ## npm CLI key facts - Latest release: 12.2.0 on 2026-09-30 16:47 UTC (GitHub tag `v12.2.0`; npm publish 16:46 UTC). Previous release on the v12 line: 12.1.0 on 2026-09-22 20:21 UTC. - Node.js 26 LTS (v26.11.0, released 2026-10-07) bundles npm 11.20.0, not npm 12. Agents running in freshly spawned Node 26 containers encounter npm 11 by default, while environments running `npm i -g npm@latest` run npm 12. - npm 12 requires Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` (`engines.node` in `package.json`). Node 20 is no longer supported in npm 12 (npm 11 supported `^20.17.0 || >=22.9.0`). - Lifecycle scripts blocked by default: npm 12 blocks dependency `preinstall`, `install`, and `postinstall` scripts unless authorized in `allowScripts` in `package.json` or bypassed with `--allow-scripts=`. Global installs print a warning and suggest `npm config set allow-scripts= --location=user`. - Git and remote tarball dependencies disabled: `allow-git` and `allow-remote` default to `none` in npm 12 (changed from `all` in npm 11). Dependencies from git URLs throw `EALLOWGIT`; remote tarball URLs throw `EALLOWREMOTE`. Set `allow-git=all` or `allow-remote=all` in `.npmrc` to restore npm 11 behaviour. - Strict CLI flag validation: unknown CLI flags, single-hyphen multi-char flags (like `-flag` instead of `--flag`), and abbreviated flags throw `EUNKNOWNCONFIG` in npm 12 instead of merely warning. - Authoritative command count: 68 commands in npm 12.2.0 vs 72 commands in npm 11.20.0. npm 12 added `npm patch` (`add`, `commit`, `update`, `ls`, `rm`) and removed 5 deprecated commands: `npm adduser` (use `npm login`), `npm shrinkwrap`, `npm star`, `npm stars`, `npm unstar`. - npm 12.1.0 introduced `read-write-stage-only` as an option for `--packages-and-scopes-permission` in `npm token create`, warning that bypass-2fa direct-publish tokens will stop working in January 2027 in favour of staged releases via `npm stage`. - 19,571,278 weekly downloads on the npm registry in the week 2026-09-28 to 2026-10-04; 10,174 GitHub stars and Artistic-2.0 licence on 2026-10-07. ## What changed in the last 5 npm CLI releases? ### npm CLI 12.2.0 (2026-09-30 16:47 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.2.0 - dist-tag: support OIDC authentication for add, del, and ls (`lib/commands/dist-tag.js`, PR #10038). ([source](https://github.com/npm/cli/pull/10038)) - update npm stage docs to reflect that it can create new packages (`docs/lib/content/commands/npm-stage.md`, PR #10017). ([source](https://github.com/npm/cli/pull/10017)) ### npm CLI 11.20.0 (2026-09-22 21:34 UTC) Release notes: https://github.com/npm/cli/releases/tag/v11.20.0 - token: backport support for read-write-stage-only granular access tokens (`lib/commands/token.js`, PR #9994). ([source](https://github.com/npm/cli/pull/9994)) - stage: display staged package status in stage command (`lib/commands/stage/index.js`, PR #9920). ([source](https://github.com/npm/cli/pull/9920)) - provenance-file takes precedence over OIDC auto-generated provenance (PR #9947). ([source](https://github.com/npm/cli/pull/9947)) ### npm CLI 12.1.0 (2026-09-22 20:21 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.1.0 - token: support read-write-stage-only granular access tokens and warn on direct-publish tokens (`lib/commands/token.js`, PR #9948). ([source](https://github.com/npm/cli/pull/9948)) - stage: display staged package status in stage command (`lib/commands/stage/index.js`, PR #9898). ([source](https://github.com/npm/cli/pull/9898)) - provenance-file config takes precedence over OIDC auto-generated provenance (PR #9882). ([source](https://github.com/npm/cli/pull/9882)) - arborist: reject uninstall arguments that carry a version specification (`lib/commands/uninstall.js`, PR #9881). ([source](https://github.com/npm/cli/pull/9881)) ### npm CLI 11.19.1 (2026-08-26 21:48 UTC) Release notes: https://github.com/npm/cli/releases/tag/v11.19.1 - pack: exempt explicit pack directory targets from allow-directory check (`lib/commands/pack.js`, PR #9916). ([source](https://github.com/npm/cli/pull/9916)) - Dependencies: updated tar to 7.5.22, undici to 6.28.0, ip-address to 10.5.0, brace-expansion to 5.0.9 (PR #9872, #9842). ([source](https://github.com/npm/cli/pull/9872)) ### npm CLI 12.0.2 (2026-07-29 21:11 UTC) Release notes: https://github.com/npm/cli/releases/tag/v12.0.2 - pack: honor min-release-age-exclude configuration option (`lib/commands/pack.js`, PR #9760). ([source](https://github.com/npm/cli/pull/9760)) - owner: use scoped registry for user lookup (`lib/commands/owner.js`, PR #9786). ([source](https://github.com/npm/cli/pull/9786)) - docs: clarify npm 12 unknown-config breaking change in changelogs (PR #9805). ([source](https://github.com/npm/cli/pull/9805)) ## Which npm CLI commands and flags were added or removed? ### npm CLI 12.1.0 → 12.2.0 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed. Method: From source (not run): compared git tree and command definitions in lib/commands/ and workspaces/config between v12.1.0 and v12.2.0. No command or flag was added or removed. - The last two releases on the npm 12 line. 12.2.0 added OIDC authentication handling to `npm dist-tag` and updated documentation for `npm stage` without altering the visible CLI surface. ### npm CLI 11.20.0 → 12.2.0 1 command added, 5 removed, 1 command with flags added; 6 command surfaces changed. Method: From source (not run): compared command definitions in lib/commands/, lib/utils/cmd-list.js, and workspaces/config between v11.20.0 (the newest npm 11 release) and v12.2.0 (the newest npm 12 release). Commands added: - `npm patch` Commands removed: - `npm adduser` - `npm shrinkwrap` - `npm star` - `npm stars` - `npm unstar` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `npm patch` | `--allow-unused-patches` `--edit-dir` `--ignore-existing` `--ignore-patch-failures` `--keep-edit-dir` `--patches-dir` `--registry` `--to` | none | - Compares the active npm 11 and npm 12 lines. `npm patch` was introduced in npm 12 to create and manage local dependency patches in `patchedDependencies`. Five legacy commands (`adduser`, `shrinkwrap`, `star`, `stars`, `unstar`) were removed. ### npm CLI 12.0.2 → 12.1.0 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed. Method: From source (not run): compared command definitions and config definitions in workspaces/config between v12.0.2 and v12.1.0. - 12.1.0 added the `read-write-stage-only` permission value to `--packages-and-scopes-permission` for `npm token create`, and added precedence handling for `provenance-file`. ### npm CLI 11.18.0 → 12.0.0 1 command added, 5 removed, 1 command with flags added; 6 command surfaces changed. Method: From source (not run): compared command definitions in lib/commands/, lib/utils/cmd-list.js, and workspaces/config between v11.18.0 and v12.0.0. Commands added: - `npm patch` Commands removed: - `npm adduser` - `npm shrinkwrap` - `npm star` - `npm stars` - `npm unstar` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `npm patch` | `--allow-unused-patches` `--edit-dir` `--ignore-existing` `--ignore-patch-failures` `--keep-edit-dir` `--patches-dir` `--registry` `--to` | none | - The major jump to npm 12. Added `npm patch` (`add`, `commit`, `update`, `ls`, `rm`) with dedicated patching flags. Removed `npm adduser`, `npm shrinkwrap`, `npm star`, `npm stars`, and `npm unstar`. Note that `npm install-scripts` and `npm stage` were introduced in late v11 in preparation for npm 12. ## What breaks when upgrading npm CLI, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Dependency lifecycle scripts (preinstall, install, postinstall) are blocked by default unless authorized by the root package's allowScripts policy. | Run `npm install-scripts approve ` to approve in a project's package.json, or pass `--allow-scripts=` (e.g. `npm i -g --allow-scripts=foo foo`). For global installs, configure once with `npm config set allow-scripts= --location=user`. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | allow-git and allow-remote now default to 'none' (previously 'all'). Installing from git repositories or direct tarball URLs fails with EALLOWGIT or EALLOWREMOTE. | Set `allow-git=all` and `allow-remote=all` in `.npmrc` or pass `--allow-git=all` / `--allow-remote=all` on the command line if your project relies on git or remote tarball dependencies. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Unknown flags on the command line, unknown configs in .npmrc when strict-npmrc is set, single-hyphen multi-character shorthands (-flag), and abbreviated flags throw EUNKNOWNCONFIG instead of warning. | Replace single-hyphen flags with double-hyphen flags (e.g. `--save` not `-save`), expand abbreviated flags to full names, and run `npm help config` to remove unrecognized options from `.npmrc`. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Legacy commands npm adduser, npm shrinkwrap, npm star, npm stars, and npm unstar were removed. npm view --json now always outputs an array. | Use `npm login` instead of `npm adduser`. Use `package-lock.json` instead of `npm-shrinkwrap.json`. Manage package stars on npmjs.com. In scripts parsing `npm view --json`, expect an array even for single version results. | | [12.0.0](https://github.com/npm/cli/releases/tag/v12.0.0) | Minimum supported Node.js version raised to ^22.22.2 || ^24.15.0 || >=26.0.0. Node 20 is no longer supported. | Upgrade the runtime environment to Node.js 22.22.2+, 24.15.0+, or 26.0.0+ before upgrading to npm 12. | ## What npm CLI errors did we reproduce, and how do I fix them? ### npm 12 blocks dependency postinstall scripts during installation (npm CLI 12.2.0) ```bash npm i -g opencode-ai@1.18.35 ``` ```text npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts: npm warn install-scripts opencode-ai@1.18.35 (postinstall: node ./postinstall.mjs) npm warn install-scripts Run `npm install -g --allow-scripts=opencode-ai` to allow these scripts once, or `npm config set allow-scripts=opencode-ai --location=user` to allow them for all global installs. # Note: install exits 0, but binary subsequently fails because postinstall was not run ``` Fix: Install with `npm i -g --allow-scripts=opencode-ai opencode-ai@latest`, or configure once via `npm config set allow-scripts=opencode-ai --location=user`. In local projects, approve using `npm install-scripts approve ` followed by `npm rebuild`. ([source](https://github.com/npm/cli/blob/v12.2.0/lib/utils/reify-output.js#L247-L285)) ### Git dependencies fail with EALLOWGIT because allow-git defaults to none (npm CLI 12.2.0) ```bash npm install git+https://github.com/user/repo.git ``` ```text npm error code EALLOWGIT npm error Fetching packages of type "git" have been disabled # exit 1 (quoted from workspaces/arborist/lib/arborist/build-ideal-tree.js line 852 at v12.2.0) ``` Fix: Run `npm install --allow-git=all git+https://github.com/user/repo.git` or set `allow-git=all` in project `.npmrc` (or `allow-git=root` if git deps are only declared in top-level package.json). ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js#L852)) ### Remote tarball dependencies fail with EALLOWREMOTE because allow-remote defaults to none (npm CLI 12.2.0) ```bash npm install https://example.com/package.tgz ``` ```text npm error code EALLOWREMOTE npm error Fetching packages of type "remote" have been disabled # exit 1 (quoted from workspaces/arborist/lib/arborist/build-ideal-tree.js line 852 at v12.2.0) ``` Fix: Run `npm install --allow-remote=all https://example.com/package.tgz` or set `allow-remote=all` in `.npmrc`. ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js#L852)) ### Single-hyphen multi-character flags throw EUNKNOWNCONFIG (npm CLI 12.2.0) ```bash npm install -save-dev lodash ``` ```text npm error code EUNKNOWNCONFIG npm error -save-dev is not a valid single-hyphen cli flag. Did you mean --save-dev? # exit 1 (quoted from workspaces/config/lib/index.js line 387 at v12.2.0) ``` Fix: Use standard double hyphens for multi-character options: `npm install --save-dev lodash` (or short single flags like `-D`). ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js#L387)) ### Invalid abbreviated CLI flags throw EUNKNOWNCONFIG (npm CLI 12.2.0) ```bash npm install --sav lodash ``` ```text npm error code EUNKNOWNCONFIG npm error Invalid abbreviated flag "--sav". Did you mean "--save"? # exit 1 (quoted from workspaces/config/lib/index.js line 597 at v12.2.0) ``` Fix: Specify the full flag name: `--save` or `--save-dev`. Abbreviated flag resolution was disabled in npm 12. ([source](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js#L597)) ### Removed commands like npm adduser fail with EUNKNOWNCOMMAND (npm CLI 12.2.0) ```bash npm adduser ``` ```text npm error code EUNKNOWNCOMMAND npm error Unknown command adduser # exit 1 (quoted from lib/npm.js line 23 at v12.2.0) ``` Fix: Use `npm login` to authenticate on the command line. Account registration and user creation must now be done on https://www.npmjs.com. ([source](https://github.com/npm/cli/blob/v12.2.0/lib/npm.js#L23)) ## npm CLI release history by month ### 2026-10: 12.2.0 (0 releases to 2026-10-07) - 12.2.0 (2026-09-30) active: Node 26 LTS bundles npm 11.20.0, while standalone installs run npm 12.2.0. ([source](https://github.com/npm/cli/releases/tag/v12.2.0)) ### 2026-09: 11.20.0 to 12.2.0 (3 releases) - 12.2.0: dist-tag OIDC authentication; updated npm stage docs. ([source](https://github.com/npm/cli/releases/tag/v12.2.0)) - 12.1.0 & 11.20.0: granular access token stage-only permission (read-write-stage-only) with deprecation warning for direct-publish tokens. ([source](https://github.com/npm/cli/releases/tag/v12.1.0)) ### 2026-08: 11.19.1 (1 release) - 11.19.1: exempt explicit pack directory targets from allow-directory restriction; dependencies updated (tar@7.5.22, undici@6.28.0). ([source](https://github.com/npm/cli/releases/tag/v11.19.1)) ### 2026-07: 10.9.9 to 12.0.2 (5 releases) - 12.0.0 (2026-07-08): major release! Block dependency lifecycle scripts by default (allowScripts); allow-git and allow-remote default to none; npm patch added; removed adduser/shrinkwrap/star. ([source](https://github.com/npm/cli/releases/tag/v12.0.0)) - 12.0.2 & 11.19.0: pack honors min-release-age-exclude; scoped registry for owner user lookup. ([source](https://github.com/npm/cli/releases/tag/v12.0.2)) ### 2026-06: 11.17.0 to 11.18.0 (2 releases) - 11.18.0: preparation for npm 12 major release and lifecycle script controls. ([source](https://github.com/npm/cli/releases/tag/v11.18.0)) - 11.17.0: introduced allow-scripts command tooling in v11 line ahead of default blocking in v12. ([source](https://github.com/npm/cli/releases/tag/v11.17.0)) ### 2026-05: 11.14.0 to 11.16.0 (4 releases) - 11.16.0: security fixes and tree-building reliability updates. ([source](https://github.com/npm/cli/releases/tag/v11.16.0)) - 11.14.0: SBOM CycloneDX improvements and Arborist dependency resolution enhancements. ([source](https://github.com/npm/cli/releases/tag/v11.14.0)) ## Sources - [npm 12.2.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.2.0) (read 2026-10-07) - [npm 12.2.0 release on npm registry](https://registry.npmjs.org/npm) (read 2026-10-07) - [npm 12.1.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.1.0) (read 2026-10-07) - [npm 11.20.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.20.0) (read 2026-10-07) - [npm 11.19.1 release on GitHub](https://github.com/npm/cli/releases/tag/v11.19.1) (read 2026-10-07) - [npm 12.0.2 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.2) (read 2026-10-07) - [npm 11.19.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.19.0) (read 2026-10-07) - [npm 10.9.9 release on GitHub](https://github.com/npm/cli/releases/tag/v10.9.9) (read 2026-10-07) - [npm 12.0.1 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.1) (read 2026-10-07) - [npm 12.0.0 release on GitHub](https://github.com/npm/cli/releases/tag/v12.0.0) (read 2026-10-07) - [npm 11.18.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.18.0) (read 2026-10-07) - [npm 11.17.0 release on GitHub](https://github.com/npm/cli/releases/tag/v11.17.0) (read 2026-10-07) - [PR #10038: dist-tag: support OIDC authentication](https://github.com/npm/cli/pull/10038) (read 2026-10-07) - [PR #10017: update npm stage docs to reflect that it can create new packages](https://github.com/npm/cli/pull/10017) (read 2026-10-07) - [PR #9948: token: support read-write-stage-only granular access tokens](https://github.com/npm/cli/pull/9948) (read 2026-10-07) - [PR #9898: stage: display staged package status](https://github.com/npm/cli/pull/9898) (read 2026-10-07) - [PR #9882: provenance-file takes precedence over OIDC auto-generated provenance](https://github.com/npm/cli/pull/9882) (read 2026-10-07) - [PR #9913: config: avoid exporting persistent allow-scripts](https://github.com/npm/cli/pull/9913) (read 2026-10-07) - [PR #9914: arborist: match allowScripts keys for local paths](https://github.com/npm/cli/pull/9914) (read 2026-10-07) - [PR #9760: pack: honor min-release-age-exclude](https://github.com/npm/cli/pull/9760) (read 2026-10-07) - [PR #9786: owner: use scoped registry for user lookup](https://github.com/npm/cli/pull/9786) (read 2026-10-07) - [PR #9805: clarify npm 12 unknown-config breaking change in changelogs](https://github.com/npm/cli/pull/9805) (read 2026-10-07) - [PR #9745: view: avoid wrapping array results](https://github.com/npm/cli/pull/9745) (read 2026-10-07) - [GitHub Changelog: Upcoming breaking changes for npm v12](https://github.blog/changelog/2026-06-09-upcoming-breaking-changes-for-npm-v12/) (read 2026-10-07) - [Node.js releases and bundled npm versions index](https://nodejs.org/dist/index.json) (read 2026-10-07) - [npm registry weekly download statistics](https://api.npmjs.org/downloads/point/last-week/npm) (read 2026-10-07) - [npm/cli repository metadata (stars, license)](https://api.github.com/repos/npm/cli) (read 2026-10-07) - [npm package.json at v12.2.0 (engines, license)](https://github.com/npm/cli/blob/v12.2.0/package.json) (read 2026-10-07) - [npm lib/commands/patch.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/commands/patch.js) (read 2026-10-07) - [npm lib/commands/install-scripts.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/commands/install-scripts.js) (read 2026-10-07) - [npm lib/utils/reify-output.js at v12.2.0 (unreviewedScripts warning)](https://github.com/npm/cli/blob/v12.2.0/lib/utils/reify-output.js) (read 2026-10-07) - [npm lib/utils/check-allow-scripts.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/utils/check-allow-scripts.js) (read 2026-10-07) - [npm lib/utils/allow-scripts-remediation.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/lib/utils/allow-scripts-remediation.js) (read 2026-10-07) - [npm lib/utils/cmd-list.js at v12.2.0 (authoritative commands)](https://github.com/npm/cli/blob/v12.2.0/lib/utils/cmd-list.js) (read 2026-10-07) - [npm lib/base-cmd.js at v12.2.0 (validateCli, EUNKNOWNCONFIG)](https://github.com/npm/cli/blob/v12.2.0/lib/base-cmd.js) (read 2026-10-07) - [npm workspaces/config/lib/index.js at v12.2.0](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/index.js) (read 2026-10-07) - [npm workspaces/config definitions at v12.2.0 (allow-git, allow-remote, strict-npmrc)](https://github.com/npm/cli/blob/v12.2.0/workspaces/config/lib/definitions/definitions.js) (read 2026-10-07) - [npm workspaces/arborist build-ideal-tree.js at v12.2.0 (#checkAllow, EALLOWGIT, EALLOWREMOTE)](https://github.com/npm/cli/blob/v12.2.0/workspaces/arborist/lib/arborist/build-ideal-tree.js) (read 2026-10-07) _Last verified: 2026-10-07._