npm dist-tag: Usage, Options & Common Errors

Manage the named tags that point at package versions.

npm dist-tag manages dist-tags - human-friendly labels like latest, beta, and next that map to specific published versions, controlling what npm install picks by default.

What it does

add points a tag at a version, rm removes a tag, and ls lists a package tags. npm install <pkg> resolves to the latest tag; npm install <pkg>@beta resolves the beta tag. Moving latest changes what every default install gets.

Common usage

npm dist-tag ls my-pkg
npm dist-tag add my-pkg@2.1.0 latest
npm dist-tag add my-pkg@3.0.0-rc.1 next
npm dist-tag rm my-pkg beta

Common CI gotcha: prereleases land on latest

Publishing a release-candidate with a plain npm publish moves the latest tag, so every default npm install suddenly gets a prerelease. Publish prereleases under a separate tag (--tag next), then promote to latest with dist-tag only when the build is stable.

npm publish --tag next
# later, promote:
npm dist-tag add my-pkg@3.0.0 latest

Related guides