What are dist-tags in npm?

Recently I had a need to use dist-tags tags when publishing a package with npm. It unfortunately took longer than I would have liked to fully understand it conceptually, so I thought I'd put this document together to provide all the information someone would need to get started.

What are dist-tags?

dist-tags or distribution tags are an optional way to provide an alias for a package that you are publishing. They are not to be confused with Git tags. Here is npm's documentation on dist-tags.

How do you add a dist-tag when publishing a package?

When you publish a package, you can add a dist-tag by including the --tag option followed by the dist-tag you'd like to use. If you do not include the --tag option, (meaning you just run npm publish), the dist-tag latest will be used by default.

Here is an example where we publish a package with the stable dist-tag:

npm publish --tag stable

An important takeaway is that using the stable dist-tag (or any dist-tag other than latest) not only associates that alias with the version of that package, but it results in the package NOT being marked as latest:

As it turns out, this describes my original need for dist-tags. I had to publish a version of a package for a previous major version and needed to ensure the version of the package I was publishing was not going to be considered the latest.

How do dist-tags come into play with installing a package?

We are all familiar with how to install a specific version of a package. We'd do something like this:

npm install some-package@3.2.0

Similarly, we can also target a specific Git tag when installing a package. Like this:

npm install some-package@v3.2.0

Just as we can target a specific package version or Git tag, we can also target a specific dist-tag like this:

npm install some-package@beta

This is why when you want to upgrade a package to the latest version, you run the following command:

npm install some-package@latest

You are simply telling npm: "Install the package with the latest dist-tag."

What values can I use for a dist-tag?

There are certain dist-tags that it seems the industry has standardized on like beta, canary, and next, but you can use almost any value that makes sense for your project. Other than latest, no tag has any special significance to npm itself.

The only restrictions are that dist-tags share a namespace with versions and Git tags so your dist-tag cannot match one of those. You will actually get an error if you try to publish a package that appears to be a semantic version (eg. 3.2.0) or tag (v3.2.0).