TypeScript icon, indicating that this package has built-in type declarations

    12.0.3 • Public • Published


    npm version Build Status Coverage Status

    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.


    Install globally:

    npm install -g npm-check-updates

    Or run with npx:

    npx npm-check-updates


    Show all new dependencies (excluding peerDependencies) 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

    Filter packages using the --filter option or adding additional cli arguments. You can exclude specific packages with the --reject option or prefixing a filter with !. Supports strings, wildcards, globs, comma-or-space-delimited lists, and regular expressions:

    # upgrade only mocha
    ncu mocha
    ncu -f mocha
    ncu --filter mocha
    # upgrade packages that start with "react-"
    ncu react-*
    ncu "/^react-.*$/"
    # upgrade everything except nodemon
    ncu \!nodemon
    ncu -x nodemon
    ncu --reject nodemon
    # upgrade only chalk, mocha, and react
    ncu chalk mocha react
    ncu chalk, mocha, react
    ncu -f "chalk mocha react"
    # upgrade packages that do not start with "react-".
    ncu \!react-*
    ncu '/^(?!react-).*$/' # mac/linux
    ncu "/^(?!react-).*$/" # windows

    How dependency updates are determined

    • Direct dependencies are updated to the latest stable version:
      • 1.21.3
    • Range operators are preserved and the version is updated:
      • ^1.2.0^2.0.0
      • 1.x2.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:
      • **
    • Prerelease and deprecated versions are ignored by default.
      • Use --pre to include prerelease versions (e.g. alpha, beta, build1235)
      • Use --deprecated to include deprecated versions
    • With --target minor, only update patch and minor:
    • With --target patch, only update patch:


    --color                      Force color in terminal
    --concurrency <n>            Max number of concurrent HTTP requests to
                                 registry. (default: 8)
    --configFileName <filename>  Config file name (default: .ncurc.{json,yml,js})
    --configFilePath <path>      Directory of .ncurc config file (default:
                                 directory of `packageFile`).
    --cwd <path>                 Working directory in which npm will be executed.
    --deep                       Run recursively in current working directory.
                                 Alias of (--packageFile '**/package.json').
    --dep <value>                Check one or more sections of dependencies only:
                                 dev, optional, peer, prod, bundle
                                 (comma-delimited). (default:
    --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, wildcard, glob, comma-or-space-delimited
                                 list, or /regex/.
    --filterVersion <matches>    Filter on package version using
                                 comma-or-space-delimited list, or /regex/.
    --format <value>             Enable additional output data, string or
                                 comma-delimited list: ownerChanged, repo.
                                 ownerChanged: shows if the package owner changed
                                 between versions. repo: infers and displays
                                 links to source code repository. (default: [])
    -g, --global                 Check global packages instead of in the current
    --greatest                   DEPRECATED. Renamed to "--target greatest".
    -i, --interactive            Enable interactive prompts for each dependency;
                                 implies -u unless one of the json options are
    -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")
    --mergeConfig                Merges nested configs with the root config file
                                 for --deep or --packageFile options (default:
    -m, --minimal                Do not upgrade newer versions that are already
                                 satisfied by the version range according to
    -n, --newest                 DEPRECATED. Renamed to "--target newest".
    -o, --ownerChanged           DEPRECATED. Renamed to "--format ownerChanged".
    --packageData <value>        Package file data (you can also use stdin).
    --packageFile <path|glob>    Package file(s) location (default:
    -p, --packageManager <name>  npm, yarn (default: "npm")
    --peer                       Check peer dependencies of installed packages
                                 and filter updates to compatible versions. Run
                                 "ncu --help --peer" for details.
    --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.
    -x, --reject <matches>       Exclude packages matching the given string,
                                 wildcard, glob, comma-or-space-delimited list,
                                 or /regex/.
    --rejectVersion <matches>    Exclude package.json versions using
                                 comma-or-space-delimited list, or /regex/.
    --removeRange                Remove version ranges from the final package
    --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. Run "ncu --help
                                 --target" for details.` (default: "latest")
    --timeout <ms>               Global timeout in milliseconds. (default: no
                                 global timeout and 30 seconds per
    -u, --upgrade                Overwrite package file with upgraded versions
                                 instead of just outputting to console.
    -V, --version                output the version number
    -h, --help                   display help for command

    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.


    $ ncu --doctor -u
    npm install
    npm run test
    ncu -u
    npm install
    npm run test
    Failing tests found:
      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": [

    Module/Programmatic Usage

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

    const ncu = require('npm-check-updates')
    (async () => {
      const upgraded = await{
        // Pass any cli option
        packageFile: '../package.json',
        upgrade: true,
        // Defaults:
        // jsonUpgraded: true,
        // silent: true,
      console.log(upgraded) // { "mypackage": "^2.0.0", ... }

    Known Issues

    • If ncu prints output that does not seem related to this package, it may be conflicting with another executable such as ncu-weather-cli or Nvidia CUDA. Try using the long name instead: npm-check-updates.
    • Windows: If npm-check-updates hangs, try setting the package file explicitly: ncu --packageFile package.json. You can run ncu --loglevel verbose to confirm that it was incorrectly waiting for stdin. See #136.


    File an issue. Please search existing issues first.


    npm i npm-check-updates

    DownloadsWeekly Downloads






    Unpacked Size

    376 kB

    Total Files


    Last publish


    • raine
    • tjunnone