1--- 2title: npm-version 3section: 1 4description: Bump a package version 5--- 6 7### Synopsis 8 9```bash 10npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] 11 12alias: verison 13``` 14 15### Configuration 16 17#### `allow-same-version` 18 19* Default: false 20* Type: Boolean 21 22Prevents throwing an error when `npm version` is used to set the new version 23to the same value as the current version. 24 25 26 27#### `commit-hooks` 28 29* Default: true 30* Type: Boolean 31 32Run git commit hooks when using the `npm version` command. 33 34 35 36#### `git-tag-version` 37 38* Default: true 39* Type: Boolean 40 41Tag the commit when using the `npm version` command. Setting this to false 42results in no commit being made at all. 43 44 45 46#### `json` 47 48* Default: false 49* Type: Boolean 50 51Whether or not to output JSON data, rather than the normal output. 52 53* In `npm pkg set` it enables parsing set values with JSON.parse() before 54 saving them to your `package.json`. 55 56Not supported by all npm commands. 57 58 59 60#### `preid` 61 62* Default: "" 63* Type: String 64 65The "prerelease identifier" to use as a prefix for the "prerelease" part of 66a semver. Like the `rc` in `1.2.0-rc.8`. 67 68 69 70#### `sign-git-tag` 71 72* Default: false 73* Type: Boolean 74 75If set to true, then the `npm version` command will tag the version using 76`-s` to add a signature. 77 78Note that git requires you to have set up GPG keys in your git configs for 79this to work properly. 80 81 82 83#### `workspace` 84 85* Default: 86* Type: String (can be set multiple times) 87 88Enable running a command in the context of the configured workspaces of the 89current project while filtering by running only the workspaces defined by 90this configuration option. 91 92Valid values for the `workspace` config are either: 93 94* Workspace names 95* Path to a workspace directory 96* Path to a parent workspace directory (will result in selecting all 97 workspaces within that folder) 98 99When set for the `npm init` command, this may be set to the folder of a 100workspace which does not yet exist, to create the folder and set it up as a 101brand new workspace within the project. 102 103This value is not exported to the environment for child processes. 104 105#### `workspaces` 106 107* Default: null 108* Type: null or Boolean 109 110Set to true to run the command in the context of **all** configured 111workspaces. 112 113Explicitly setting this to false will cause commands like `install` to 114ignore workspaces altogether. When not set explicitly: 115 116- Commands that operate on the `node_modules` tree (install, update, etc.) 117will link workspaces into the `node_modules` folder. - Commands that do 118other things (test, exec, publish, etc.) will operate on the root project, 119_unless_ one or more workspaces are specified in the `workspace` config. 120 121This value is not exported to the environment for child processes. 122 123#### `workspaces-update` 124 125* Default: true 126* Type: Boolean 127 128If set to true, the npm cli will run an update after operations that may 129possibly change the workspaces installed to the `node_modules` folder. 130 131 132 133#### `include-workspace-root` 134 135* Default: false 136* Type: Boolean 137 138Include the workspace root when workspaces are enabled for a command. 139 140When false, specifying individual workspaces via the `workspace` config, or 141all workspaces via the `workspaces` flag, will cause npm to operate only on 142the specified workspaces, and not on the root project. 143 144This value is not exported to the environment for child processes. 145 146### Description 147 148Run this in a package directory to bump the version and write the new data 149back to `package.json`, `package-lock.json`, and, if present, 150`npm-shrinkwrap.json`. 151 152The `newversion` argument should be a valid semver string, a valid second 153argument to [semver.inc](https://github.com/npm/node-semver#functions) (one 154of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, 155`prerelease`), or `from-git`. In the second case, the existing version will 156be incremented by 1 in the specified field. `from-git` will try to read 157the latest git tag, and use that as the new npm version. 158 159If run in a git repo, it will also create a version commit and tag. This 160behavior is controlled by `git-tag-version` (see below), and can be 161disabled on the command line by running `npm --no-git-tag-version version`. 162It will fail if the working directory is not clean, unless the `-f` or 163`--force` flag is set. 164 165If supplied with `-m` or [`--message` config](/using-npm/config#message) option, 166npm will use it as a commit message when creating a version commit. If the 167`message` config contains `%s` then that will be replaced with the resulting 168version number. For example: 169 170```bash 171npm version patch -m "Upgrade to %s for reasons" 172``` 173 174If the [`sign-git-tag` config](/using-npm/config#sign-git-tag) is set, then the 175tag will be signed using the `-s` flag to git. Note that you must have a default 176GPG key set up in your git config for this to work properly. For example: 177 178```bash 179$ npm config set sign-git-tag true 180$ npm version patch 181 182You need a passphrase to unlock the secret key for 183user: "isaacs (http://blog.izs.me/) <i@izs.me>" 1842048-bit RSA key, ID 6C481CF6, created 2010-08-31 185 186Enter passphrase: 187``` 188 189If `preversion`, `version`, or `postversion` are in the `scripts` property 190of the package.json, they will be executed as part of running `npm 191version`. 192 193The exact order of execution is as follows: 194 1951. Check to make sure the git working directory is clean before we get 196 started. Your scripts may add files to the commit in future steps. 197 This step is skipped if the `--force` flag is set. 1982. Run the `preversion` script. These scripts have access to the old 199 `version` in package.json. A typical use would be running your full 200 test suite before deploying. Any files you want added to the commit 201 should be explicitly added using `git add`. 2023. Bump `version` in `package.json` as requested (`patch`, `minor`, 203 `major`, etc). 2044. Run the `version` script. These scripts have access to the new `version` 205 in package.json (so they can incorporate it into file headers in 206 generated files for example). Again, scripts should explicitly add 207 generated files to the commit using `git add`. 2085. Commit and tag. 2096. Run the `postversion` script. Use it to clean up the file system or 210 automatically push the commit and/or tag. 211 212Take the following example: 213 214```json 215{ 216 "scripts": { 217 "preversion": "npm test", 218 "version": "npm run build && git add -A dist", 219 "postversion": "git push && git push --tags && rm -rf build/temp" 220 } 221} 222``` 223 224This runs all your tests and proceeds only if they pass. Then runs your 225`build` script, and adds everything in the `dist` directory to the commit. 226After the commit, it pushes the new commit and tag up to the server, and 227deletes the `build/temp` directory. 228 229### See Also 230 231* [npm init](/commands/npm-init) 232* [npm run-script](/commands/npm-run-script) 233* [npm scripts](/using-npm/scripts) 234* [package.json](/configuring-npm/package-json) 235* [config](/using-npm/config) 236