pnpm publish

레지스트리에 패키지를 게시합니다.

pnpm [-r] publish [<tarball|folder>] [--tag <tag>]
     [--access <public|restricted>] [options]

When publishing a folder or a tarball, pnpm includes a package-root README in the registry metadata if the manifest has no readme value. It recognizes README.md, other README files with npm-compatible Markdown extensions (such as README.markdown and README.mdown), and README. It prefers README.md, then another Markdown README, then README. This is separate from --embed-readme, which embeds the README in the published manifest.

When publishing a pre-built tarball, pnpm rejects manifests, README files, and archive metadata larger than 64 MiB.

워크스페이스 내부의 패키지를 게시할 때, 워크스페이스 루트의 LICENSE 파일이 패키지와 함께 압축됩니다(패키지에 자체 라이선스가 있는 경우는 제외).

package.json의 publishConfig 필드를 사용하여 게시 전에 일부 필드를 재정의할 수 있습니다. publishConfig.directory를 사용하여 게시되는 하위 디렉터리를 사용자 지정할 수도 있습니다(보통 서드파티 빌드 도구를 사용하는 경우).

이 명령을 재귀적으로 실행하면(pnpm -r publish) pnpm은 아직 레지스트리에 게시되지 않은 버전을 가진 모든 패키지를 게시합니다.

옵션#

--recursive, -r#

workspace에 있는 모든 패키지를 게시합니다.

--json#

JSON 형식으로 정보를 표시합니다.

--tag <tag>#

지정된 태그가 있는 패키지를 게시합니다. 기본적으로 pnpm publish는 latest 태그를 업데이트합니다.

예시:

# foo 패키지 디렉토리 내부
pnpm publish --tag next
# foo의 다음 버전을 사용하려는 프로젝트에서
pnpm add foo@next

--access <public|restricted>#

게시된 패키지가 공개 또는 제한되어야 하는지 여부를 레지스트리에 알려줍니다.

--no-git-checks#

Skip the git checks. By default, pnpm checks that the working tree is clean, that the current branch is the publish branch, and that the branch is up to date with the remote.

--publish-branch <branch>#

  • Default: master or main
  • 유형: String

The branch that publishing is allowed from. It overrides the publishBranch setting. Without either, the current branch must be master or main. In CI, a detached HEAD skips the branch check.

--ignore-scripts#

Don't run the publish lifecycle scripts.

--embed-readme#

  • 기본값: false
  • 유형: Boolean

Embed the README contents in the published manifest. The embedReadme setting sets the default.

--force#

현재 버전이 이미 레지스트리에 있는 경우에도 패키지를 게시하려고 합니다.

--batch#

When publishing recursively (pnpm -r publish), send all selected packages to the registry in a single PUT /-/pnpr/v0/publish request instead of one request per package.

대상 레지스트리는 일괄 게시 엔드포인트를 구현해야 합니다(pnpr는 구현되어 있음). 구현하지 않은 레지스트리는 ERR_PNPM_BATCH_PUBLISH_UNSUPPORTED 오류로 보고됩니다. 일괄 처리는 전부 아니면 전무 방식으로 이루어집니다: 일괄 처리에 포함된 패키지 중 하나라도 유효성 검사에 실패하면 어떤 패키지도 게시되지 않습니다.

A package that declares publishConfig.variants can be published in a batch to a registry declared with serverType: pnpr. In such a batch, pnpm first uploads the archives it packed for every package to the registry's staging area, and checks that the registry still holds each archive another job uploaded with --upload-variant. The batch then references all of them by integrity. One batch references at most 256 archives per registry; a batch with variants that needs more fails with ERR_PNPM_BATCH_PUBLISH_TOO_MANY_ARCHIVES.

The selected packages are grouped by the registry each one publishes to, and one request is sent per group. Every package in a group must authenticate with the same credential. A scope-specific token shared across the group is fine, and mismatched credentials for one registry are rejected before anything is published, rather than after part of the release went out. The publish and postpublish scripts run after each completed group.

--no-variants#

Publish only the archive that targets any of a package that declares publishConfig.variants. Without it, pnpm refuses to publish such a package to a registry that is not declared with serverType: pnpr, because a version published without its variants can't get them later.

--upload-variant <target>#

Pack the archive of the publishConfig.variants entry that lists this target, upload it to the registry's staging area, and print <target>=<integrity>. Nothing is published: a later pnpm publish --variant-integrity publishes the version with it. Can be repeated, and any uploads the archive of every other host.

This lets each job of a CI matrix upload the archive it built. Every job must publish as the same account, which trusted publishing gives every job of a workflow. Uploading the same archive again renews it. The registry keeps an uploaded archive for a day.

value=$(pnpm publish --upload-variant linux-x64-musl)

With --json, pnpm prints the package's name and version, and each archive's tag, targets, and integrity.

--variant-integrity <target>=<integrity>#

Publish the version from archives other jobs uploaded with --upload-variant, given by the values they printed. Repeat it once per entry of publishConfig.variants, the any entry included, naming each by any one of its targets. With --recursive, name the package first: <name>~<target>=<integrity>.

pnpm packs none of the archives of a package that a value names. Before publishing, it checks that every entry has exactly one value and that the registry still holds each archive for this account. It fails naming the archive whose upload job has to run again. With --recursive, a selected package that no value names is packed and published as usual, and each value must name exactly one selected, publishable project.

--release-notes <file>#

A file of release notes to send to a registry declared with serverType: pnpr. The publish fails when the file does not exist. Publishing one package, the notes are its version notes. Publishing several packages with --batch, they are the notes of the whole release.

In a workspace that uses pnpm's versioning, give the summary to pnpm version -r --release-notes instead: pnpm version -r composes every note of the release, and pnpm publish fails with ERR_PNPM_RELEASE_NOTES_FROM_VERSIONING when --release-notes is given for packages it composed notes for.

Without this option, pnpm sends each package's notes for the version it publishes:

  • In a workspace that uses pnpm's versioning, the notes composed from its change intents.
  • Otherwise, the section of the package's CHANGELOG.md under the heading of the version, as changesets (## 1.4.0) and Keep a Changelog (## [1.4.0] - 2026-10-28) write it, without the heading itself.

pnpm prints where each package's notes came from. Notes are at most 64 KiB and may not contain control characters other than line feed and tab, or bidirectional override characters. pnpm checks this before anything is uploaded. Registries not declared with serverType: pnpr receive no notes.

--no-release-notes#

Send no release notes.

--publication-name <name>#

The name of the release that --batch publishes to a registry declared with serverType: pnpr, such as v12.0.0. It may contain letters, digits, ., _, +, and -, is at most 214 bytes long, and is not a number, since a number names a release by its identifier. In a workspace that uses pnpm's versioning, the release is named after the version of its epic lead or its one fixed group by default.

--skip-manifest-obfuscation#

게시된 매니페스트에서 원래의 packageManager 필드와 게시 라이프사이클 스크립트를 제거하지 않고 유지합니다. The pnpm field is still omitted, except for pnpm.config.

--publish-wait-timeout <milliseconds>#

Added in: v12.7.0

  • 기본값: 0
  • Type: Number (non-negative integer)

Wait for the exact published version to appear in the registry's install metadata. Then check that a HEAD request to its tarball URL returns HTTP 200. This helps release workflows handle registry delays, such as npm's publish-time malware scanning. A value of 0 disables the check.

pnpm publish --publish-wait-timeout 600000
pnpm -r publish --publish-wait-timeout 600000 --report-summary

The timeout is in milliseconds and includes registry requests and retry delays. Each package has its own timeout, including selected versions that already exist. For a new upload, the timeout starts after the registry accepts it. For an existing version, it starts when pnpm begins its availability check. With --batch, each uploaded registry group shares one timeout.

Recursive publishing also checks selected versions that already exist in the registry. Without --batch, pnpm confirms availability before publishing dependent packages. With --batch, pnpm checks each registry group after its upload. The publish and postpublish scripts run after the corresponding check succeeds.

If confirmation times out, the command fails with ERR_PNPM_PUBLISH_AVAILABILITY_TIMEOUT. The upload remains accepted and may become available later. Do not publish the same version again. Use --report-summary with recursive publishing to record accepted uploads even if the command fails.

Invalid registry responses or non-retryable HTTP errors, such as authentication failures, cause ERR_PNPM_PUBLISH_AVAILABILITY_CHECK_FAILED.

--dry-run skips availability checks. pnpm stage publish ignores the configured default and rejects an explicit positive --publish-wait-timeout, because staged versions cannot be installed. The check does not download the archive or install the package. It does not verify the archive's contents.

Use publishWaitTimeout to set a default.

--report-summary#

게시된 패키지 목록을 pnpm-publish-summary.json에 저장합니다. 게시된 패키지 목록을 보고하기 위해 다른 도구를 사용할 때 유용합니다.

pnpm-publish-summary.json 파일의 예시:

pnpm-publish-summary.json
{
  "publishedPackages": [
    {
      "name": "foo",
      "version": "1.0.0"
    },
    {
      "name": "bar",
      "version": "2.0.0"
    }
  ]
}

When a recursive publish fails after the registry accepted some of the uploads, the summary still lists the packages that were published.

--dry-run#

실제로 레지스트리에 게시하는 것을 제외하고 게시가 수행하는 모든 작업을 수행합니다.

--otp#

이중 인증이 필요한 패키지를 게시할 때, 이 옵션은 일회용 암호를 지정할 수 있습니다.

PNPM_CONFIG_OTP 환경 변수를 통해 OTP를 제공할 수도 있습니다:

export PNPM_CONFIG_OTP='<your OTP here>'
pnpm publish --no-git-checks

레지스트리가 OTP를 요청하는데 환경 변수나 --otp 플래그로 제공하지 않은 경우, pnpm이 OTP 코드를 직접 묻습니다.

레지스트리가 웹 기반 인증을 요청하면, pnpm은 URL과 함께 스캔 가능한 QR 코드를 출력합니다.

--provenance#

지원되는 클라우드 CI/CD 시스템에서 게시하는 경우, 패키지는 빌드 및 게시된 위치와 공개적으로 연결됩니다.

Under trusted publishing, pnpm attaches provenance to a public package from a public repository on its own. Use --no-provenance (or --provenance=false) to publish without it, for example from a self-hosted runner. Use provenance to set a default.

For a package with publishConfig.variants, one statement names every archive the publish supplies: the archive that targets any and each platform variant, including those other jobs uploaded with --upload-variant. A version without an any archive gets one that the registry generates for npm clients, and the statement does not name it. --upload-variant itself does not sign provenance.

Running a publish to a registry declared with serverType: pnpr again is safe, with or without provenance. A rerun that signs provenance again sends a new statement, so the registry answers that the version is already published. pnpm then reports the version as published only when all of these hold:

  • the version's release record names the same archives, the archive that targets any and each platform variant;
  • when the rerun signs provenance, the version has a statement naming every one of those archives;
  • the dist-tag the publish sets points at the version.

Otherwise it fails with ERR_PNPM_PUBLISHED_RELEASE_DIFFERS and names what differs. A version without an any archive is compared by its variants only.

--filter <package_selector>#

필터링에 대해 자세히 알아보세요.

환경설정#

You can also set gitChecks, publishBranch, publishWaitTimeout, and provenance options in the pnpm-workspace.yaml file.

예시:

pnpm-workspace.yaml
gitChecks: false
publishBranch: production

publishBranch#

  • Default: master or main
  • 유형: String

Sets the default for --publish-branch. Configure it in pnpm-workspace.yaml.

The PNPM_CONFIG_PUBLISH_BRANCH environment variable overrides pnpm-workspace.yaml. The command-line option takes precedence over both.

publishWaitTimeout#

Added in: v12.7.0

  • 기본값: 0
  • Type: Number (non-negative integer)

Sets the default timeout in milliseconds for --publish-wait-timeout. Configure it in pnpm-workspace.yaml or the global config.yaml:

pnpm-workspace.yaml
publishWaitTimeout: 600000

The PNPM_CONFIG_PUBLISH_WAIT_TIMEOUT environment variable overrides the configuration files. The command-line option takes precedence over both, including --publish-wait-timeout=0 to disable waiting for one command.

provenance#

  • 기본값: undefined
  • 유형: Boolean

Sets the default for --provenance. When unset, trusted publishing decides. Set it to false to never attach provenance:

pnpm-workspace.yaml
provenance: false

The PNPM_CONFIG_PROVENANCE environment variable overrides the configuration files. The command-line option takes precedence over both.

Life cycle scripts#

  • prepublishOnly
  • prepublish
  • prepack
  • prepare
  • postpack
  • publish
  • postpublish