새로운 pnpm 12에서 달라진 점

pnpm 12 is a rewrite of pnpm in Rust, and it is stable. Upgrading should not feel like a migration. Apart from the differences below, it keeps the commands, flags, settings, and lockfile format of pnpm 11, and the documentation applies to both versions.

Eight things differ. Six of them change a result, and two reject command-line syntax that pnpm 11 accepted. 이 글에서는 이를 한곳에 모았습니다.

프로젝트 인식 전역 바이너리#

A globally installed node, deno, or bun now runs the version the current project pins.

A project pins a runtime through devEngines.runtime or by installing the runtime as a dependency. Run node inside that project and you get the pinned version. Run it outside any project and you get the global one. You no longer need a separate version manager for this.

이를 제어하는 설정은 globalShims이며, 전체 설명은 프로젝트 인식 전역 bin에 있습니다.

Git 종속성 해석#

For repositories on GitHub, GitLab, and Bitbucket, a specifier now only says which repository you want, not how to reach it. All of these name the same dependency and resolve the same way:

kevva/is-positive
github:kevva/is-positive
git+https://github.com/kevva/is-positive.git
git+ssh://git@github.com/kevva/is-positive.git

Each resolves through the host's HTTPS URL, and pnpm never records an SSH URL for those hosts. How a machine reaches the host is that machine's Git configuration, not something the project decides. A lockfile written on a laptop with SSH keys installs on a CI runner without them.

pnpm 11 tried transports in turn and could record git@github.com:owner/repo.git, which then failed for everyone without a key for that host. If an older lockfile has such an entry, run pnpm update <package> once to re-resolve it. pnpm does not rewrite the entry on its own. The lockfile is the record of what to install, and pnpm leaves it alone until you ask.

To reach private repositories over SSH, tell Git to rewrite the URL:

git config --global url."git@github.com:".insteadOf https://github.com/

pnpm shells out to git, so the rewrite applies to every Git operation pnpm runs. Unknown hosts and URLs with embedded credentials are covered in How Git dependencies are resolved.

패키지 관리자 지정#

pnpm 12 can install the other package managers: npm, Yarn Classic, Yarn Berry, Yarn 6 (yarnpkg/zpm), and Bun. As a result, naming one of them means the tool, not the npm package that shares its name.

Those npm packages are not the tool. yarn on npm stops at Classic. Yarn 4 is published as @yarnpkg/cli-dist. Yarn 6 is not on npm at all. node and deno on npm are wrappers that download a build. 그래서 이전에는 pnx yarn@4 install이 버전 누락으로 실패했고, pnpm add -g yarn을 실행하면 Yarn 1이 설치되었습니다.

pnpm 11 pnpm 12
pnpm add yarn npm 패키지 yarn을 설치합니다 프로젝트의 패키지 관리자를 packageManager / devEngines.packageManager에 기록합니다
pnpm add -g yarn 설치 대상: Yarn Classic 현재 Yarn 계열을 설치합니다
pnpm add -g node / pnpm add -g deno 래퍼 패키지를 설치합니다 해당 Node.js 또는 Deno 릴리스를 설치합니다
pnx node@22 / pnx deno 래퍼 패키지를 실행합니다 해당 릴리스를 실행합니다
전역으로 설치된 패키지 관리자 항상 전역 사본 프로젝트에 고정된 버전이 있으면 이를 따릅니다

A specifier that points at a specific package still installs that package. pnpm add yarn@npm:yarn@1.22.22 gives you the npm package, and pnx yarn@yarnpkg/berry runs Yarn from its repository.

Two more things follow. A git-hosted dependency is built with the package manager its own repository asks for, so a repository that uses Yarn installs on a machine that has only pnpm. And pnpm shim add yarn links a yarn command that runs whatever version the current project pins. pnpm never creates such a shim as a side effect of pnpm setup or an install, because the shim shadows the rest of your PATH.

전체 설명은 기타 패키지 관리자에 있습니다.

순환 종속성 그래프의 lockfile#

pnpm 12 breaks dependency cycles at a fixed place. It orders the packages in a cycle by package ID and always cuts the same edge, no matter where the install entered the cycle. pnpm 11 cut wherever it happened to walk in.

The lockfile now depends only on the dependency graph. Reorder the packages globs in pnpm-workspace.yaml, reorder entries in package.json, or install twice, and you get the same bytes. In pnpm 11 a project with cycles could get a different lockfile each time. Workspaces with many cycles also resolve peers 2–3× faster and use about 25% less memory. Their lockfiles shrink too, because a package inside a cycle no longer gets a separate peer variant for every path that reaches it.

Existing lockfiles keep working. --frozen-lockfile installs them as they are, and an install that doesn't re-resolve leaves them untouched. The first install that does re-resolve rewrites the peer variants of cyclic packages, so expect a one-time lockfile diff. Details in How peers are resolved.

On Linux, the default packageImportMethod: auto now tries a hardlink before a reflink. Hardlinks are cheaper to create, and on btrfs this roughly halves the time an install spends materializing node_modules from a warm store.

Cloning is still the second choice. A store that refuses a hardlink gets a clone, and a store that refuses that too gets a copy. packageImportMethod: clone still asks for a clone outright. Pick that if you edit files inside node_modules, because a hardlinked file is the store's file. Nothing changes on ext4, which never supported cloning, so auto already hardlinked there. macOS keeps clone-first because APFS clonefile is fast.

pnpm 11 keeps clone-first on Linux. Changing what the default writes to disk is not something for a point release.

engineStrict and optional subtrees#

With engineStrict on, pnpm 12 fails the install when a package that is being installed depends, through regular dependencies, on a package with an incompatible engine. It no longer matters that the whole subtree sits under an optionalDependencies entry. pnpm 11 installs the package and prints an install-check warning.

What gets skipped has not changed. A package reachable only through optional edges, or through a package that was itself skipped, is still skipped in both versions (#13286).

pnpm install --resolution-only가 제거됨#

pnpm 12는 이 플래그를 구현하지 않으며 이를 거부합니다:

error: unexpected argument '--resolution-only' found

The flag existed to print peer dependency issues. pnpm peers check does that instead. It reads the issues from the lockfile, so it needs neither a re-resolution nor an install:

pnpm peers check

If a CI script calls --resolution-only, replace it before switching to pnpm 12.

Explicit frozen-lockfile values#

pnpm install --frozen-lockfile false is no longer supported. Use pnpm install --no-frozen-lockfile to disable frozen-lockfile mode. To enable it, use pnpm install --frozen-lockfile without a separate true argument (pnpm/pnpm#14741).

사용해 보기#

latest on npm still points at the pnpm 11 line, so install pnpm 12 from the latest-12 tag. 아직 Homebrew, winget, Scoop, Chocolatey에서는 제공하지 않습니다. Installing pnpm 12 lists the ways to install it.

발생하는 문제가 있다면 문제를 보고해 주세요.