What does the npm version command do to your repo before a release?

The npm version command bumps the version in package.json, updates the lockfile, and in a git repository makes a commit and a tag. It also runs preversion, version and postversion scripts if you defined them. It refuses to run on a dirty working tree unless you force it.

What it changes

According to the npm documentation, the command updates package.json, plus package-lock.json and npm-shrinkwrap.json when they exist. You can give it an explicit semver string, a release type such as patch, minor or major, a pre-release variant, or from-git to take the latest git tag.

In a git repo it creates a version commit and a tag. Passing the no-git-tag-version option skips both. The message option sets the commit text, and a percent s in the message is replaced with the new version.

The order of events

The docs give this sequence:

1. Check that the working directory is clean.
2. Run the preversion script.
3. Bump the version.
4. Run the version script.
5. Commit and tag.
6. Run the postversion script.

npm version patch -m "Release %s"
git push --follow-tags

That second line pushes the commit and the tag together. If your publish workflow triggers on tags, the push is what starts it, so this is the moment your release actually begins. Pair it with a ruleset that protects release tags and an approval step on the publish job.

Why the clean tree rule helps

npm fails if there are uncommitted changes, unless you use the force option. That protects you from tagging a version that does not match what you reviewed. Avoid force in your release routine. If it complains, find out what changed.

Be careful with the lifecycle scripts

The three scripts run with your privileges on your laptop. If you copy a project or accept a pull request that edits them, they run when you cut a release. Treat scripts in package.json like code in a build, and read them in review. Our post on which npm lifecycle scripts run on install covers the consumer side.

Signed tags

The sign-git-tag setting, when true, signs the tag with GPG. The docs say this requires a default GPG key in your git config. A signed tag lets others check that a person with your key created it, which matters little to npm itself, since the registry does not read git tags, but helps anyone auditing your source. See setting up signed commits.

A short release routine

1. Pull, run tests and the audit, and confirm a clean tree.
2. Run the version command with the release type.
3. Review the diff of the commit it made.
4. Push the commit and tag.
5. Let CI publish, not your laptop.
6. Test the package in a clean install, as in testing the published artifact before you announce.

Quick check

Sources

• npm docs: npm version

Last reviewed: 19 October 2026.