版本：11 & 12

安装

前言

如果你不使用独立脚本或 @pnpm/exe 来安装 pnpm，则您的系统需要安装 Node.js（至少 v22）。

提示

Looking for pnpm 12? It is currently in beta and installed differently from pnpm 11. See Installing the pnpm 12 beta.

使用独立脚本安装

即使没有安装 Node.js，也可以使用以下脚本安装 pnpm。

在 Windows 上

警告

如果你以这种方式安装 pnpm，Windows Defender 有时可能会阻止我们的可执行文件。

由于此问题，我们目前建议在 Windows 上使用 npm 或 Corepack 安装 pnpm。

使用 PowerShell：

Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

在 Windows 上，Microsoft Defender 会显著减慢软件包的安装速度。你可以通过在具有管理员权限的 PowerShell 窗口中执行以下命令，将 pnpm 添加到 Microsoft Defender 的排除文件夹列表中：

Add-MpPreference -ExclusionPath $(pnpm store path)

在 POSIX 系统上

Not supported on Intel macOS in pnpm 11

On pnpm 11, the standalone script does not run on Intel Macs (darwin-x64). 请改用 npm、 Corepack 或 Homebrew。有关上下文，请参阅 #11423。

pnpm 12 ships an Intel macOS build again, so this limitation doesn't apply to it.

curl -fsSL https://get.pnpm.io/install.sh | sh -

如果你没有安装 curl，也可以使用 wget：

wget -qO- https://get.pnpm.io/install.sh | sh -

Linux 运行时要求

安装脚本会根据你系统的 libc 选择 glibc 或 musl 构建版本，并为 Alpine 和其他基于 musl 的发行版提供单独的 musl 构建版本。 glibc 构建需要 glibc 2.27 或更高版本以及 libatomic.so.1 — 大多数完整发行版中都有这两个，但最小容器镜像中可能缺少它们。如果你看到 error while loading shared libraries: libatomic.so.1，请使用发行版的软件包管理器安装该库：

Debian/Ubuntu：apt-get install -y libatomic1
Fedora/RHEL：dnf install -y libatomic

提示

你可以使用 pnpm runtime 命令来安装 Node.js。

在 Docker 容器中

# bash
wget -qO- https://get.pnpm.io/install.sh | ENV="$HOME/.bashrc" SHELL="$(which bash)" bash -
# sh
wget -qO- https://get.pnpm.io/install.sh | ENV="$HOME/.shrc" SHELL="$(which sh)" sh -
# dash
wget -qO- https://get.pnpm.io/install.sh | ENV="$HOME/.dashrc" SHELL="$(which dash)" dash -

安装特定版本

在运行安装脚本之前，你可以选择设置环境变量 PNPM_VERSION 来安装特定版本的 pnpm：

curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=<version> sh -

使用 Corepack

由于 Corepack 中的签名过时问题，请先将 Corepack 更新至最新版本：

npm install --global corepack@latest

从 v16.13 开始，Node.js 附带 Corepack 用于管理包管理器。这是一项实验性功能，因此你需要通过运行如下脚本来启用它：

提示

如果你使用 pnpm runtime 安装了 Node.js，则 Corepack 不会安装在您的系统中，你需要单独安装它。请参阅 #4029。

corepack enable pnpm

这会自动将 pnpm 安装在你的系统上。

你可以通过下列命令固定项目所用的 pnpm 版本：

corepack use pnpm@latest-11

这会添加一个 packageManager 字段到你本地的 package.json，指示 Corepack 始终在该项目上使用特定的版本。如果你想要可复现性，这可能很有用，因为所有使用 Corepack 的开发人员都将使用与你相同的版本。当一个新版本的 pnpm 发布时，你可以重新运行上述命令。

警告

Corepack cannot install pnpm 12 yet. It expects the pnpm package to contain a bin/pnpm.mjs file, which the native pnpm 12 package does not have. Use pnpm self-update, npm, or the standalone script to install the beta.

使用其他包管理器

使用 npm

我们提供了两个 pnpm CLI 包， pnpm 和 @pnpm/exe。 On pnpm 12 the two are identical, so there is no reason to prefer one over the other; the difference below applies to pnpm 11.

pnpm 是 pnpm 的普通版本，需要 Node.js 才能运行。自 v11 版本起，pnpm 以纯 ESM 格式分发。
@pnpm/exe 与 Node.js 一起打包成可执行文件，因此它可以在没有安装 Node.js 的系统上使用。在 Linux 系统上，glibc 和 musl 版本均已提供，并且会自动选择正确的版本；glibc 版本需要 glibc 2.27 或更高版本以及 libatomic.so.1（详情请参阅 Linux 运行时要求）。 不适用于 Intel macOS (darwin-x64) — 请改用 pnpm，参见 #11423。

npx pnpm@latest-11 dlx @pnpm/exe@latest-11 setup

或者

npm install -g pnpm@latest-11

使用 HomeBrew

如果你已经安装了这个包管理器，你可以使用下面的命令安装 pnpm：

brew install pnpm

使用 winget

如果你安装了 winget ，你可以使用以下命令安装 pnpm：

winget install -e --id pnpm.pnpm

使用 Scoop

如果你已经安装了 Scoop，你可以使用下面的指令安装 pnpm：

scoop install nodejs-lts pnpm

使用 Choco

如果你已经安装了 Chocolatey，你可以使用下面的指令安装 pnpm：

choco install pnpm

提示

你想在 CI 服务器上使用 pnpm 吗？参见：持续集成。

Installing the pnpm 12 beta

警告

pnpm 12 is a rewrite of pnpm in Rust and is currently in beta. It is not recommended for production use yet. Please report any issues you run into.

pnpm 12 has no intentional breaking changes compared to pnpm 11, so the rest of this documentation applies to both versions. Only installation differs while v12 is in beta: it is published under the next-12 tag on npm and as a prerelease on GitHub, so Homebrew, winget, Scoop and Chocolatey don't offer it yet.

Using pnpm

If you already have pnpm v11.10.0 or newer, this is the easiest way to switch:

pnpm self-update next-12

pnpm links the native binary directly, so nothing else is needed. Note that inside a project that pins pnpm through the packageManager field, self-update only updates that pin instead of installing pnpm globally.

Using npm

If you don't have pnpm installed yet:

npm install -g --allow-scripts=pnpm pnpm@next-12

提示

--allow-scripts=pnpm is required on npm 11.16 and newer, which blocks install scripts by default. The published package is a small wrapper whose preinstall script replaces it with the native binary for your platform, so without the flag pnpm is left as a placeholder file that fails to run. Older versions of npm run install scripts anyway and ignore the flag, so the command above works on any version. For the same reason, don't install pnpm 12 with --ignore-scripts or --no-optional. If you install it with pnpm or Bun, allow the build scripts of the pnpm package.

Node.js 18 or newer is needed to run that install script, but not to run pnpm afterwards — pnpm 12 is a native binary.

Using a standalone script

Set PNPM_VERSION to the exact beta version (the POSIX script does not accept npm dist-tags).

On POSIX systems:

curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=12.0.0-beta.2 sh -

On Windows, using PowerShell:

$env:PNPM_VERSION="12.0.0-beta.2"; Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

This installs pnpm without requiring Node.js, and unlike pnpm 11 it also works on Intel macOS.

兼容性

以下是各版本 pnpm 与各版本 Node.js 之间的兼容性表格。

Node.js	pnpm 8	pnpm 9	pnpm 10	pnpm 11	pnpm 12
Node.js 14	❌	❌	❌	❌	❌
Node.js 16	✔️	❌	❌	❌	❌
Node.js 18	✔️	✔️	✔️	❌	✔️
Node.js 20	✔️	✔️	✔️	❌	✔️
Node.js 22	✔️	✔️	✔️	✔️	✔️
Node.js 24	✔️	✔️	✔️	✔️	✔️
Node.js 26	✔️	✔️	✔️	✔️	✔️

pnpm 12 only needs Node.js when it is installed from npm; the version installed by the standalone script runs without Node.js.

问题排查

如果 pnpm 损坏并且你无法通过重新安装来修复，你可能需要将其从 PATH 中手动删除。

假设你在运行 pnpm install 时遇到以下错误：

C:\src>pnpm install
internal/modules/cjs/loader.js:883
  throw err;
  ^



Error: Cannot find module 'C:\Users\Bence\AppData\Roaming\npm\pnpm-global\4\node_modules\pnpm\bin\pnpm.js'
←[90m    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:880:15)←[39m
←[90m    at Function.Module._load (internal/modules/cjs/loader.js:725:27)←[39m
←[90m    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)←[39m
←[90m    at internal/main/run_main_module.js:17:47←[39m {
  code: ←[32m'MODULE_NOT_FOUND'←[39m,
  requireStack: []
}

首先，尝试通过运行 which pnpm 来找到 pnpm 的位置。如果你使用的是 Windows，请运行 where.exe pnpm.*。你将获得 pnpm 命令的位置，例如：

$ which pnpm
/c/Program Files/nodejs/pnpm

现在你已经知道了 pnpm CLI 的所在目录，打开它并删除所有与 pnpm 相关的文件（如 pnpm.cmd、 pnpx.cmd、 pnpm 等）。完成后，再次安装 pnpm。现在它应该按照预期正常工作。

更新 pnpm

要更新 pnpm，请运行 self-update 命令：

pnpm self-update

卸载 pnpm

如果你需要从系统中删除 pnpm CLI 以及它写入磁盘的任何文件，请参阅卸载 pnpm。

前言​

使用独立脚本安装​

在 Windows 上​

在 POSIX 系统上​

在 Docker 容器中​

安装特定版本​

使用 Corepack​

使用其他包管理器​

使用 npm​

使用 HomeBrew​

使用 winget​

使用 Scoop​

使用 Choco​

Installing the pnpm 12 beta​

Using pnpm​

Using npm​

Using a standalone script​

兼容性​

问题排查​

更新 pnpm​

卸载 pnpm​

前言