npm-check-updates

npm-check-updates upgrades your package.json dependencies to the latest versions, ignoring specified versions.

• maintains existing semantic versioning policies, i.e. "express": "^4.0.0" to "express": "^5.0.0".
• only modifies package.json file. Run npm install to update your installed packages and package-lock.json.

• Red = major upgrade (and all major version zero)
• Cyan = minor upgrade
• Green = patch upgrade

You may also want to consider npm-check. Similar purpose, different features.

Installation

npm install -g npm-check-updates

Usage

Show any new dependencies for the project in the current directory:

$ ncu
Checking package.json
[====================] 5/5 100%

 express           4.12.x  →   4.13.x
 multer            ^0.1.8  →   ^1.0.1
 react-bootstrap  ^0.22.6  →  ^0.24.0
 react-a11y        ^0.1.1  →   ^0.2.6
 webpack          ~1.9.10  →  ~1.10.5

Run ncu -u to upgrade package.json

Upgrade a project's package file:

Make sure your package file is in version control and all changes have been committed. This will overwrite your package file.

$ ncu -u
Upgrading package.json
[====================] 1/1 100%

 express           4.12.x  →   4.13.x

Run npm install to install new versions.

$ npm install      # update installed packages and package-lock.json

Check global packages:

ncu -g           # add -u to get a one-line command for upgrading

You can include or exclude specific packages using the --filter and --reject options. They accept strings, comma-or-space-delimited lists, or regular expressions:

# match mocha and should packages exactly
$ ncu mocha             # shorthand for ncu -f mocha (or --filter)
$ ncu one, two, three

# exclude packages
$ ncu -x nodemon        # shorthand for ncu --reject nodemon

# match packages that start with "gulp-" using regex
$ ncu "/^gulp-.*$/"

# match packages that do not start with "gulp-".
$ ncu '/^(?!gulp-).*$/' # mac/linux
$ ncu "/^(?!gulp-).*$/" # windows

Options

--concurrency <n>            Max number of concurrent HTTP requests to
                             registry. (default: 8)
--configFilePath <path>      Directory of .ncurc config file (default:
                             directory of `packageFile`).
--configFileName <filename>  Config file name (default: .ncurc.{json,yml,js})
--cwd <path>                 Working directory in which npm will be executed.
--dep <dep>                  Check one or more sections of dependencies only:
                             prod, dev, peer, optional, bundle
                             (comma-delimited).
--deprecated                 Include deprecated packages.
--doctor                     Iteratively installs upgrades and runs tests to
                             identify breaking upgrades. Run "ncu --doctor"
                             for detailed help. Add "-u" to execute.
--enginesNode                Include only packages that satisfy engines.node
                             as specified in the package file.
-e, --errorLevel <n>         Set the error level. 1: exits with error code 0
                             if no errors occur. 2: exits with error code 0
                             if no packages need updating (useful for
                             continuous integration). (default: 1)
-f, --filter <matches>       Include only package names matching the given
                             string, comma-or-space-delimited list, or
                             /regex/.
-g, --global                 Check global packages instead of in the current
                             project.
--greatest                   DEPRECATED. Renamed to "--target greatest".
-i, --interactive            Enable interactive prompts for each dependency;
                             implies -u unless one of the json options are
                             set,
-j, --jsonAll                Output new package file instead of
                             human-readable message.
--jsonDeps                   Like `jsonAll` but only lists `dependencies`,
                             `devDependencies`, `optionalDependencies`, etc
                             of the new package data.
--jsonUpgraded               Output upgraded dependencies in json.
-l, --loglevel <n>           Amount to log: silent, error, minimal, warn,
                             info, verbose, silly. (default: "warn")
-m, --minimal                Do not upgrade newer versions that are already
                             satisfied by the version range according to
                             semver.
-n, --newest                 DEPRECATED. Renamed to "--target newest".
-p, --packageManager <name>  npm, yarn (default: "npm")
-o, --ownerChanged           Check if the package owner changed between
                             current and upgraded version.
--packageData <string>       Package file data (you can also use stdin).
--packageFile <path>         Package file location (default: ./package.json).
--pre <n>                    Include -alpha, -beta, -rc. (default: 0; default
                             with --newest and --greatest: 1).
--prefix <path>              Current working directory of npm.
-r, --registry <url>         Third-party npm registry.
--removeRange                Remove version ranges from the final package
                             version.
--semverLevel <value>        DEPRECATED. Renamed to --target.
-s, --silent                 Don't output anything (--loglevel silent).
-t, --target <value>         Target version to upgrade to: latest, newest,
                             greatest, minor, patch. (default: "latest")
--timeout <ms>               Global timeout in milliseconds. (default: no
                             global timeout and 30 seconds per
                             npm-registery-fetch).
-u, --upgrade                Overwrite package file with upgraded versions
                             instead of just outputting to console.
-x, --reject <matches>       Exclude packages matching the given string,
                             comma-or-space-delimited list, or /regex/.
-V, --version                output the version number
-h, --help                   display help for command

How dependency updates are determined

• Direct dependencies are updated to the latest stable version:
  • 2.0.1 → 2.2.0
  • 1.2 → 1.3
  • 0.1.0 → 1.0.1
• Range operators are preserved and the version is updated:
  • ^1.2.0 → ^2.0.0
  • 1.x → 2.x
  • >0.2.0 → >0.3.0
• "Less than" is replaced with a wildcard:
  • <2.0.0 → ^3.0.0
  • 1.0.0 < 2.0.0 → ^3.0.0
• "Any version" is preserved:
  • * → *
• with --target minor, only update patch and minor:
  • 0.1.0 → 0.2.1
• with --target patch, only update patch:
  • 0.1.0 → 0.1.2

Doctor Mode

Usage: ncu --doctor [-u] [options]

Iteratively installs upgrades and runs tests to identify breaking upgrades. Add -u to execute (modifies your package file, lock file, and node_modules).

To be more precise:

1. Runs npm install and npm test to ensure tests are currently passing.
2. Runs ncu -u to optimistically upgrade all dependencies.
3. If tests pass, hurray!
4. If tests fail, restores package file and lock file.
5. For each dependency, install upgrade and run tests.
6. When the breaking upgrade is found, saves partially upgraded package.json (not including the breaking upgrade) and exits.

Example:

$ ncu --doctor -u
npm install
npm run test
ncu -u
npm install
npm run test
Failing tests found:
/projects/myproject/test.js:13
  throw new Error('Test failed!')
  ^
Now let's identify the culprit, shall we?
Restoring package.json
Restoring package-lock.json
npm install
npm install --no-save react@16.0.0
npm run test
  ✓ react 15.0.0 → 16.0.0
npm install --no-save react-redux@7.0.0
npm run test
  ✗ react-redux 6.0.0 → 7.0.0
Saving partially upgraded package.json

Configuration Files

Use a .ncurc.{json,yml,js} file to specify configuration information. You can specify file name and path using --configFileName and --configFilePath command line options.

For example, .ncurc.json:

{
  "upgrade": true,
  "filter": "express",
  "reject": [
    "@types/estree",
    "ts-node"
  ]
}

Module/Programmatic Usage

npm-check-updates can be required as a module:

const ncu = require('npm-check-updates')

const upgraded = await ncu.run({
  // Pass any cli option.
  // Defaults:
  jsonUpgraded: true,
  silent: true
})

console.log(upgraded) // { "mypackage": "^2.0.0", ... }

Known Issues

• Windows: If npm-check-updates hangs, run ncu --loglevel verbose to see if it is waiting for stdin. If so, try setting the package file explicitly: ncu --packageFile package.json. See #136.

Also search the issues page.

Problems?

File an issue. Please search existing issues first.