pnpm add <pkg>

安装软件包及其依赖的任何软件包。默认情况下,任何新软件包都被安装为生产依赖项。

摘要:#

命令 含义
pnpm add sax 保存到 dependencies
pnpm add -D sax 保存到 devDependencies
pnpm add -O sax 保存到 optionalDependencies
pnpm add -g sax 安装全局依赖
pnpm add sax@next 安装 next 标签的版本
pnpm add sax@3.0.0 指定 3.0.0 版本
pnpm add lodash@npm:awesome-lodash Install awesome-lodash as lodash
pnpm add crate:serde Add a Cargo crate
pnpm add pypi:httpx Add a Python package

支持的软件包来源#

pnpm 支持从各种来源安装软件包。请参阅 支持的软件包源 页面了解详细文档:

  • npm 源
  • JSR 源
  • 工作区包
  • 本地文件系统 (tarballs和目录)
  • 远程 tarball
  • Git 仓库(包含语义化版本控制、子目录等)
  • crates.io and PyPI, through the crate: and pypi: prefixes

Package aliases#

To install an npm package under a different local name, use an npm: alias:

pnpm add <alias>@npm:<package>
pnpm add <alias>@npm:<package>@<version-or-tag>

The package after npm: may be scoped and versioned. 例如:

pnpm add babel-core@npm:@babel/core@8.0.6

This writes babel-core as the dependency name while resolving @babel/core@8.0.6 as the target package. The npm: part is the npm package-alias protocol, not a named registry; registry routing still follows the target package's default or scope-specific npm registry configuration.

See Aliases for more examples.

添加包管理器或运行时#

新增于:v12.0.0-rc.6(仅限 pnpm v12)

Naming a package manager (npm, yarn or bun) records which one the project uses instead of installing the npm package that shares the name:

pnpm add yarn@4

writes "packageManager": "yarn@4.18.0". npm and Bun are recorded as a range in devEngines.packageManager instead. Each write removes the other field. Naming a runtime (node, deno) records it under engines.runtime, as the explicit node@tool:22 spelling does since v12.13.0. bun is both, and is declared as the project's package manager unless you ask for the runtime (pnpm add bun@tool:1.3.0).

在全局范围内,pnpm add -g yarn 会安装当前的 Yarn 版本,而不是仅包含 Classic 版本的 yarn 包;同样,pnpm add -g node@22 会直接安装该 Node.js 版本,而不是安装一个负责下载该版本的包装程序。

A specifier that locates a package rather than asking for a released version, such as pnpm add yarn@npm:yarn@1.22.22 or pnpm add yarn@yarnpkg/berry, installs what it names, as an ordinary dependency.

Adding the Rust toolchain#

Added in: v12.11.0

rust names the Rust toolchain, not the npm package of that name. The version is a Rust release channel: a version (1.95.0 or 1.95), stable, beta, nightly, or a dated channel such as nightly-2026-01-01. A bare rust asks for stable.

In a project, pnpm add rust@1.95 pins the toolchain in the rust-toolchain.toml that governs the project, the nearest one at or above it in the workspace. It creates one in the project if there is none, and changes only the channel, keeping the rest of the file. With cargo.enabled, the toolchain is installed too. Nothing is added to package.json.

pnpm add -g rust@stable installs the toolchain globally. The cargo, rustc, and other Rust commands run it outside projects whose rust-toolchain.toml names a toolchain of their own. pnpm update -g rust installs the newest release of its channel, pnpm ls -g lists it, and pnpm remove -g rust removes it.

Protocol-prefixed selectors#

A selector may carry the protocol in front of the name rather than after it:

pnpm add jsr:@scope/pkg
pnpm add npm:pkg@^1.0.0
pnpm add workspace:pkg@*

Package URLs#

Added in: v12.5.0

pnpm add accepts Package URLs for npm, Cargo, and Python packages:

pnpm add pkg:npm/express@4.18.2
pnpm add pkg:cargo/serde@1.0.188
pnpm add pkg:pypi/requests@2.31.0

These save dependencies to package.json, Cargo.toml, and pyproject.toml, respectively. Cargo and Python use their ecosystem configuration. pkg is a reserved specifier prefix, regardless of case, and cannot be used as a named registry alias.

配置项#

--save-prod, -P, -p#

将指定的依赖安装为常规的 dependencies。

--save-dev, -D, -d#

将指定的依赖安装为 devDependencies。

--save-optional, -O, -o#

将指定的依赖安装为 optionalDependencies。

--save-exact, -E, -e#

已保存的依赖项将被配置确切版本,而不是使用 pnpm 的默认语义化版本范围运算符。

--save-build#

Install crate: packages as Cargo build dependencies.

--save-peer#

使用 --save-peer 会把依赖安装为开发依赖,并添加到 peerDependencies 中。 --no-save-peer overrides a savePeer: true setting.

--save-types#

Added in: v12.6.0

Saves available @types/* packages in devDependencies alongside registry dependencies. Packages that declare bundled TypeScript types are skipped.

pnpm add express --save-types
# saves express to dependencies, @types/express to devDependencies

Set saveTypes: true in pnpm-workspace.yaml to enable this by default. --no-save-types overrides that setting.

--save-prefix <prefix>#

The prefix of the saved version range: ^, ~, = for an explicit exact pin, or an empty string for a bare exact version. Overrides the savePrefix setting.

--tilde#

Added in: v12.6.0

Alias for --save-prefix=~. Saved dependencies will be configured with a tilde range (~1.2.3) instead of the default caret range (^1.2.3).

--save-catalog#

将新依赖项保存到默认的目录(catalog)。

--save-catalog-name <catalog_name>#

将新的依赖项保存到指定的目录(catalog)。

--config#

Save the dependency to configDependencies.

Since v12.12.0, the saved range follows the same rules as for a dependency in package.json.

--ignore-workspace-root-check#

Adding a new dependency to the root workspace package fails, unless you pass --ignore-workspace-root-check or target the root with -w (--workspace-root).

例如:pnpm add debug -w.

--global, -g#

全局安装软件包。有关详细信息,请参阅 全局包。

每个以空格分隔的软件包均安装到其各自独立的目录中。若要将多个包捆绑为单个隔离的安装(使其共享依赖并能被同时移除),请以逗号分隔的形式传入这些包,例如 pnpm add -g eslint,prettier。

--workspace#

仅添加在工作空间中找到的依赖项。 The dependency is saved with the workspace: protocol and linked from the workspace project that provides it. When no workspace project provides the package, the command fails instead of falling back to the registry.

--allow-build#

允许在安装期间执行安装的包名列表。

示例:

pnpm --allow-build=esbuild add my-bundler

这将运行 esbuild 的 postinstall 脚本,并将其添加到 pnpm-workspace.yaml 的 allowBuilds 字段中。因此, esbuild 将来将始终被允许运行其脚本。

Since v12.4.0, prefixing a name with ! denies the build instead:

pnpm add --allow-build=!core-js my-bundler

writes allowBuilds: { core-js: false }, so the package is never asked about again. Global installs (pnpm add -g) record the denial too.

--lockfile-only#

Update package.json and pnpm-lock.yaml without downloading dependencies or writing node_modules.

--force#

Reinstall every package the lockfile names, relinking packages that an earlier install already linked.

--lockfile-dir <dir>#

The directory in which pnpm-lock.yaml is created. Same as the lockfileDir setting.

--prod, --production#

Leave devDependencies out of node_modules.

--dev#

Leave dependencies out of node_modules.

--[no-]optional#

Include or exclude optionalDependencies from node_modules.

--[no-]auto-dedupe#

Enable or disable the autoDedupe setting for this install.

--ignore-scripts#

Do not run the lifecycle scripts of the project or its dependencies. Same as the ignoreScripts setting.

--ignore-pnpmfile#

Disable the pnpmfile hooks, including the pnpmfiles of config dependencies.

--registry#

Specify the registry to use for this installation:

pnpm add --registry=https://registry.npmjs.org/ lodash

--filter <package_selector>#

阅读更多有关过滤的内容。

--cpu=#

覆盖要安装的本机模块的 CPU 架构。可接受的值与 package.json 中的 cpu 字段相同,这个字段来自 process.arch。

--os=<name>#

覆盖本机的 OS 原生安装。可接受的值与 package.json 中的 os 字段相同,这个字段来自 process.platform。

--libc=<name>#

覆盖要安装的原生模块的 libc。可接受的值与 package.json 中的 libc 字段相同。