npm publish: Usage, Options & Common Errors

Publish a package version to the npm registry.

npm publish packs the current package and uploads it to the registry under the version in package.json. In release pipelines it is where auth and version-collision errors surface.

What it does

Builds the tarball (honoring the files field and .npmignore), runs prepublishOnly/prepack, and uploads to the configured registry. The version in package.json must not already exist. Scoped packages default to private unless --access public is set.

Common usage

npm publish                          # publish current version
npm publish --access public          # publish a scoped pkg publicly
npm publish --tag beta               # publish under the "beta" dist-tag
npm publish --dry-run                # show what would be published

Common CI error: E403 / E409 on publish

Release CI fails with "npm error code E403 / You do not have permission" (bad/missing token or private scope) or "npm error code E409 / cannot publish over previously published version". For E403, set a valid automation token in NPM_TOKEN and add --access public for scoped packages. For E409, bump the version - a tag cannot be republished.

# CI auth via token, then version-bumped publish:
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
npm version patch --no-git-tag-version
npm publish --access public

Key options

Related guides