How to rollback an npm package

Mask your broken version and better understand how npm dist-tags works



Here at Outbrain, we work with CI/CD to publish our npm packages, and a few days ago, I updated a small package that the deployment process is using, validated the code, and released the package through our pipeline. The CI ran tests and published the new version. 🎉

But an hour passed, and developers started complaining about pipelines beginning to fail, and I quickly found out that my update was the reason! So quickly, I found the problem and fixed it. But as I ran the pipeline, I got the SAME error that everyone got, and I couldn’t release my fix! 😱

After some more digging, I found out that the CI/CD process always uses the latest version of the package that I updated, and because I broke the latest version of the package, I couldn’t release my fix to update the package. So, what could I do? 🤔


When we want to install a new package to our repo, we can specify a specific version or let npm decide. By default, npm installs the “latest” version, but “latest” doesn’t always mean the newest version.

When we run npm install without specifying a tag, NPM will automatically resolve to the latest tag.

Custom Tags

When we publish a new version of our package, npm automatically assigns this new version with the “latest” tag, but we can specify a specific tag instead of “latest.”

This command will publish our newest version under the “best” tag, but what happens to the “latest” tag? Well, we can check by using the dist-tag command. The dist-tag command allows us to list, set, and remove tags.

If we run this command, we’ll see all the tags of our package.

As you can see, the newly published version is now under the “best” tag, but the “latest” tag still points to the old version!

If we want to remove the “best” tag, run the following command:

To add a new tag, we can run the following:


So to mask our flawed version, we can override the latest tag with the working version. In the case of our package, all we need to run is

And that is it! The next time someone will run npm install npm-rollback NPM will install the version 1.0.0 instead of the newest version 1.0.1



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store