●Change8

Migrating to pnpm v12.0.0-alpha.16

Version v12.0.0-alpha.16 introduces 2 breaking changes. This guide details how to update your code.

Released: 7/19/2026

2
Breaking Changes
4
Migration Steps
47
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

pnpm runtime installationpnpm.allowedDeprecatedVersionsinstall-test commandrecursive commandmulti commandm commandvirtualStoreOnly settingenableModulesDir settingenableGlobalVirtualStore settingERR_PNPM_CONFIG_CONFLICT_VIRTUAL_STORE_ONLY_WITH_NO_MODULES_DIRpnpm-workspace.yamlnode_modulespnpm addpnpm removeERR_PNPM_HOIST_PATTERN_DIFFpnpm install --ignore-scriptsnode_modules/.modules.yamlpendingBuildspnpm rebuild --pendingpnpm installpatchedDependenciesERR_PNPM_UNUSED_PATCHallowUnusedPatches settingpnpm add -goptionalDependenciesdevDependenciespnpm-lock.yamlsupportedArchitecturespnpm setupPNPM_HOMEpnpm self-updategit+file:git+https:codeload.github.comenableGlobalVirtualStoreERR_PNPM_LOCKFILE_MISSING_DEPENDENCYnodeLinker: hoistednodeLinker: isolatedLockfile is up to date, resolution step is skippedpnpm fetchImporting packages to virtual storeIf-Modified-Since304 Not Modified--os--cpu--libcstrictDepBuilds

Breaking Changes

●Issue #1

The `virtualStoreOnly` setting, when combined with `enableModulesDir: false`, now fails with `ERR_PNPM_CONFIG_CONFLICT_VIRTUAL_STORE_ONLY_WITH_NO_MODULES_DIR` unless `enableGlobalVirtualStore` is on. This is because the standard virtual store resides within `node_modules`.

●Issue #2

`pnpm install` now fails with `ERR_PNPM_UNUSED_PATCH` when an entry in `patchedDependencies` does not match any installed package. To revert to the previous warning behavior, set `allowUnusedPatches: true` in `pnpm-workspace.yaml`.

Migration Steps

  1. 1
    If you are using `virtualStoreOnly` with `enableModulesDir: false`, ensure `enableGlobalVirtualStore` is enabled or adjust your configuration to avoid `ERR_PNPM_CONFIG_CONFLICT_VIRTUAL_STORE_ONLY_WITH_NO_MODULES_DIR`.
  2. 2
    If you encounter `ERR_PNPM_UNUSED_PATCH` errors, either update your `patchedDependencies` to match installed packages or set `allowUnusedPatches: true` in your `pnpm-workspace.yaml` to revert to a warning.
  3. 3
    If you previously relied on `pnpm add` to move dependencies between groups, be aware that it now moves them instead of creating duplicates.
  4. 4
    If you previously relied on `pnpm add <pkg>` without a `--save-*` flag to always save to `dependencies`, be aware that it now updates the dependency in its existing group.

Release Summary

This release enhances pnpm's runtime installation parity across Node.js, Deno, and Bun, introduces native commands like `install-test` and `recursive`, and improves the robustness of installations and dependency management, including better handling of patched dependencies and optional packages.

Need More Details?

View the full release notes and all changes for pnpm v12.0.0-alpha.16.

View Full Changelog