npm 19 🌐 Managing Package Tags (npm dist-tag) - KandZ

⏱️ Estimated read: 12 min | |

Distribution tags (dist-tags) are human-readable labels that point to specific versions of a published package. The latest tag is the one npm uses by default when a consumer runs npm install package-name without a version or tag specifier. Every other tag—next, beta, stable, canary—is a custom pointer that the publisher creates and manages. The npm dist-tag command is the interface for adding, removing, and listing these pointers, and understanding it is the difference between a release process that can stage prereleases safely and one that accidentally promotes an unstable build to every consumer .

Key point: Publishing a package automatically moves the latest tag to the new version. To publish a prerelease without making it the default install target, the --tag flag must be used during publish. Forgetting this flag is the most common way a beta build becomes the version that npm install resolves to.

Why dist-tags exist

The default resolution problem. When a consumer runs npm install lodash, npm does not install the highest version number. It installs the version pointed to by the latest tag. This decouples the act of publishing from the act of making a version the default. A publisher can release 2.0.0-beta.1 without making it the version that every new install receives, as long as the publish uses --tag next or --tag beta instead of the default .

The release channel problem. Projects often maintain multiple streams of development simultaneously. A stable tag might point to the latest production-ready release, a next tag to the upcoming major version, and a canary tag to the most recent commit from the main branch. Consumers can opt into a channel with npm install package@next, while the default npm install package continues to resolve the stable release through the latest tag .

The promotion problem. A version that was published under a beta tag can be promoted to latest without republishing. The npm dist-tag add command moves the latest pointer to that version. This is the standard graduation path: publish as beta, test with early adopters, then promote the same tarball to latest once it is validated. Republishing is not required because the tarball already exists in the registry .

The rollback problem. If a version is published to latest and a critical bug is discovered, the dist-tag add command can move the latest pointer back to the previous version. The broken version still exists in the registry, but new installs resolve the older, working version. This is faster than unpublishing and does not break consumers who already have the broken version in their lockfiles .

a. Listing and Inspecting Tags

The npm dist-tag ls command shows every tag on a package and the version each one points to. When run without a package name, it operates on the package in the current directory. When run with a package name, it queries the registry for that package’s tags .

# List the dist-tags for the package in the current directory
npm dist-tag ls

# List the dist-tags for a specific published package
npm dist-tag ls react

The output is a simple key-value list. The latest entry is always present on a published package. Custom tags appear alongside it. A package that has never had a custom tag will show only latest. A package with an active prerelease channel will show both latest and next or beta.

# Example output for a package with a prerelease channel
latest: 1.4.2
next: 2.0.0-beta.3

This inspection step is the first action in any tag operation. Before moving a tag, the current position should be confirmed. Before promoting a prerelease, the version that latest currently points to should be recorded so that the promotion can be reversed if necessary.

b. Adding and Moving Tags

The npm dist-tag add command points a tag at a specific version. The version must already exist in the registry. The command does not publish a new version; it only moves the pointer .

# Point the "stable" tag at version 1.4.0
npm dist-tag add example-package@1.4.0 stable

# Promote a beta version to latest
npm dist-tag add example-package@2.0.0 latest

The syntax is <package>@<version> followed by the tag name. The package name can be scoped (@scope/package) or unscoped. The version must be an exact version string; a range is not accepted because the tag must point to a single tarball.

The add command is also the mechanism for creating a new tag that did not exist before. If a project decides to introduce a canary channel, the first dist-tag add creates the tag and points it at the chosen version. Subsequent publishes with --tag canary will move it forward.

The command requires authentication and, if the account has auth-and-writes 2FA enabled, an OTP. The --otp flag supplies the code on the command line, or the CLI prompts for it .

c. Removing Tags and Publishing with a Tag

The npm dist-tag rm command removes a tag from a package. The tag no longer appears in dist-tag ls, and consumers who attempt to install using that tag receive an error. The versions themselves are not affected; only the pointer is removed .

# Remove the "canary" tag
npm dist-tag rm example-package canary

Removing a tag is appropriate when a release channel is retired. It is not appropriate for removing latest, because that tag is required for the default install behavior. If latest points to a version that should no longer be the default, the correct action is to move it with dist-tag add, not to remove it.

The --tag flag on npm publish is what prevents a prerelease from becoming latest. When a package is published without the flag, npm moves latest to the new version. When the flag is present, npm moves the specified tag instead .

# Publish a prerelease under the "next" tag
npm publish --tag next

# Publish a stable release under "latest" (the default)
npm publish

The publish command with --tag next creates the next tag if it does not exist and points it at the published version. The latest tag remains where it was. This is the mechanism that allows a project to ship 2.0.0-beta.1 without breaking every consumer who runs npm install package.

A caveat worth noting is the namespace collision between tags and versions. Tags and version numbers share the same slot in the install specifier (package@something). A tag that looks like a semver range is rejected. v1.4 cannot be a tag because semver interprets it as a range. The recommendation is to use tag names that do not begin with a number or the letter v .

Complete Example Session

# ============================================
# PART 1: INSPECT THE CURRENT TAGS
# ============================================
# Show all tags on the package
npm dist-tag ls example-package
# latest: 1.4.2


# ============================================
# PART 2: PUBLISH A PRERELEASE UNDER A CUSTOM TAG
# ============================================
# The package.json version is 2.0.0-beta.1
npm publish --tag next
# The "next" tag is created and points to 2.0.0-beta.1
# The "latest" tag remains at 1.4.2


# ============================================
# PART 3: VERIFY THE TAG MOVEMENT
# ============================================
npm dist-tag ls example-package
# latest: 1.4.2
# next: 2.0.0-beta.1


# ============================================
# PART 4: CONSUMERS OPT INTO THE PRERELEASE
# ============================================
# In a consumer project
npm install example-package@next
# Installs 2.0.0-beta.1


# ============================================
# PART 5: GRADUATE THE PRERELEASE
# ============================================
# After testing, promote the same version to latest
npm dist-tag add example-package@2.0.0-beta.1 latest


# ============================================
# PART 6: VERIFY THE PROMOTION
# ============================================
npm dist-tag ls example-package
# latest: 2.0.0-beta.1
# next: 2.0.0-beta.1


# ============================================
# PART 7: PUBLISH A NEW STABLE VERSION
# ============================================
# After graduating, the next stable release is 2.0.0
npm publish
# The "latest" tag moves to 2.0.0 automatically


# ============================================
# PART 8: ROLLBACK IF NECESSARY
# ============================================
# If 2.0.0 has a critical bug, move latest back
npm dist-tag add example-package@1.4.2 latest


# ============================================
# PART 9: REMOVE A RETIRED TAG
# ============================================
# The "next" channel is no longer needed
npm dist-tag rm example-package next


# ============================================
# PART 10: FINAL STATE
# ============================================
npm dist-tag ls example-package
# latest: 1.4.2
# The rollback is in effect; the "next" tag is gone

The ten parts trace the lifecycle of a prerelease channel: publish under a custom tag, verify the separation from latest, promote when ready, and roll back if necessary. Part 5 is the promotion step, and Part 8 is the rollback step. Both use the same add command with a different target version.

Quick Reference

dist-tag Commands

Command	Purpose
`npm dist-tag ls`	List all tags and their versions
`npm dist-tag add pkg@version tag`	Point a tag at a version
`npm dist-tag rm pkg tag`	Remove a tag
`npm publish --tag <tag>`	Publish under a custom tag

Tag Behavior

Tag	Significance
`latest`	Default for `npm install pkg`
`next`	Common convention for upcoming version
`beta`, `stable`, `canary`	Custom channels, no special npm meaning

Publishing and Tags

Command	Effect on `latest`
`npm publish`	Moves `latest` to new version
`npm publish --tag next`	`latest` unchanged; `next` moves

Tag Naming Rules

Rule	Reason
Do not begin with a number	Avoids semver range collision
Do not begin with `v`	Avoids version-like parsing
Use descriptive names	`beta`, `next`, `stable`

Best Practices

✅ Do This:

# Check current tags before moving any pointer
npm dist-tag ls example-package                                        # ✅

# Use --tag for prereleases to protect latest
npm publish --tag next                                                 # ✅

# Promote with dist-tag add instead of republishing
npm dist-tag add example-package@2.0.0 latest                          # ✅

# Roll back latest by moving it to the previous version
npm dist-tag add example-package@1.4.2 latest                          # ✅

❌ Don’t Do This:

# Publish a prerelease without --tag
npm publish  # moves latest to the prerelease                          # ❌

# Remove latest
npm dist-tag rm example-package latest  # breaks default install       # ❌

# Use tag names that look like versions
npm dist-tag add example-package@1.0.0 v1.4  # rejected               # ❌

# Assume dist-tag add publishes a version
# The version must already exist in the registry                       # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Prerelease becomes default install	Published without `--tag`	Use `--tag next` or move `latest` back
Tag add fails	Version does not exist	Publish the version first
Tag name rejected	Looks like a semver range	Use a name not starting with a number or `v`
`latest` removed by accident	Used `dist-tag rm` on `latest`	Re-add `latest` pointing to a valid version
Consumer cannot install custom tag	Tag was removed or mistyped	Verify with `dist-tag ls`

Real-World Examples

1. List Tags

npm dist-tag ls example-package

2. Publish Under Next

npm publish --tag next

3. Promote to Latest

npm dist-tag add example-package@2.0.0 latest

4. Roll Back Latest

npm dist-tag add example-package@1.4.2 latest

5. Create Stable Tag

npm dist-tag add example-package@1.4.0 stable

6. Remove Retired Tag

npm dist-tag rm example-package canary

7. Install a Tagged Version

npm install example-package@next

8. Verify Tag Points to Version

npm dist-tag ls example-package | grep next

9. 2FA OTP for Tag Command

npm dist-tag add example-package@1.0.0 stable --otp=123456

10. Check Default Install Target

npm view example-package dist-tags.latest

Visual

Tag Pointers to Versions

┌──────────────────────────────────────────────────────────────┐
│  REGISTRY                                                    │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Version 1.4.2   │◄──── latest (default install)          │
│  └─────────────────┘                                        │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Version 2.0.0-  │◄──── next                              │
│  │ beta.1          │                                        │
│  └─────────────────┘                                        │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Version 1.3.0   │◄──── stable                            │
│  └─────────────────┘                                        │
│                                                              │
│  npm install pkg          → 1.4.2                            │
│  npm install pkg@next     → 2.0.0-beta.1                     │
│  npm install pkg@stable   → 1.3.0                            │
│                                                              │
│  Tags are independent pointers.                              │
│  Moving one does not affect the others.                      │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Publish with and without Tag

┌──────────────────────────────────────────────────────────────┐
│  WITHOUT --tag                WITH --tag next                │
│                                                              │
│  npm publish                  npm publish --tag next         │
│         │                              │                     │
│         ▼                              ▼                     │
│  ┌─────────────────┐            ┌─────────────────┐         │
│  │ latest moves    │            │ next moves      │         │
│  │ to new version  │            │ to new version  │         │
│  │                 │            │                 │         │
│  │ next unchanged  │            │ latest unchanged│         │
│  └─────────────────┘            └─────────────────┘         │
│                                                              │
│  Default installs change.      Default installs stay stable. │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Promotion and Rollback

┌──────────────────────────────────────────────────────────────┐
│  BEFORE PROMOTION                                            │
│  latest: 1.4.2                                               │
│  next:   2.0.0-beta.1                                        │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ npm dist-tag    │                                        │
│  │ add pkg@2.0.0-  │                                        │
│  │ beta.1 latest   │                                        │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  AFTER PROMOTION                                             │
│  latest: 2.0.0-beta.1                                        │
│  next:   2.0.0-beta.1                                        │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Bug discovered  │                                        │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ npm dist-tag    │                                        │
│  │ add pkg@1.4.2   │                                        │
│  │ latest          │                                        │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  AFTER ROLLBACK                                              │
│  latest: 1.4.2                                               │
│  next:   2.0.0-beta.1                                        │
│                                                              │
│  Same command for promotion and rollback.                    │
│  Only the target version differs.                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Tag Naming Collision

┌──────────────────────────────────────────────────────────────┐
│  TAG NAME: v1.4                                              │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ npm dist-tag    │                                        │
│  │ add pkg@1.4.0   │                                        │
│  │ v1.4            │                                        │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ REJECTED        │                                        │
│  │                 │                                        │
│  │ Semver interprets│                                       │
│  │ v1.4 as a range │                                        │
│  │ >=1.4.0 <1.5.0  │                                        │
│  └─────────────────┘                                        │
│                                                              │
│  FIX: Use a name that does not start with a number or v     │
│  Example: "stable", "release-1.4", "lts"                    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Default tag	`latest`
List tags	`npm dist-tag ls <package>`
Add or move tag	`npm dist-tag add <package>@<version> <tag>`
Remove tag	`npm dist-tag rm <package> <tag>`
Publish under custom tag	`npm publish --tag <tag>`
`latest` behavior on publish	Moves automatically unless `--tag` is used
Tag naming rule	Avoid names starting with a number or `v`
Promotion	`dist-tag add` to `latest`
Rollback	`dist-tag add` to previous version

Key takeaways:

latest is the default install target, not the highest version. When a consumer runs npm install package, npm resolves the latest tag. A higher version number with a different tag is not installed unless the consumer explicitly requests that tag .
npm publish --tag protects latest from prereleases. Publishing without the flag moves latest to the new version. Publishing with --tag next moves the next tag instead, leaving latest where it was. This is the mechanism that keeps beta builds out of default installs .
Promotion and rollback use the same command. npm dist-tag add points a tag at a version. Promoting a beta to latest and rolling back a broken release to the previous version are the same operation with different target versions .
Tags and versions share a namespace. A tag that looks like a semver range is rejected. Names starting with a number or v are the common cause. Use descriptive names like stable, next, or canary .
dist-tag ls is the verification step. Before moving a tag, confirm its current position. After moving it, confirm the new position. The command is read-only and has no side effects, which makes it safe to run at any point.

Remember: Dist-tags are pointers, not properties of the version. A version can exist in the registry without any tag pointing to it. The latest tag is the only one with special significance to npm itself; every other tag is a convention that the publisher defines and the consumer opts into. The dist-tag command manipulates these pointers without republishing tarballs. This separation between “published” and “default” is what allows a project to ship prereleases, maintain multiple release channels, and roll back a bad release without breaking the consumers who depend on the default install behavior.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!