npm-check-updates

What is npm-check-updates?

npm-check-updates is a command-line tool that allows you to find and update outdated npm dependencies in your project. It helps you keep your project dependencies up-to-date by checking for newer versions and updating your package.json file accordingly.

What are npm-check-updates's main functionalities?

Check for outdated dependencies

This command checks for any outdated dependencies in your project and lists them along with the latest versions available.

ncu

Update package.json with latest versions

This command updates your package.json file with the latest versions of all dependencies.

ncu -u

Interactive mode

This command runs npm-check-updates in interactive mode, allowing you to selectively choose which dependencies to update.

ncu -i

Filter dependencies

This command filters the dependencies to check for updates only within a specific scope or matching a specific pattern.

ncu '/^@my-scope/'

Upgrade specific dependencies

This command checks for updates and upgrades only the specified dependency (e.g., lodash).

ncu lodash

Other packages similar to npm-check-updates

npm-check

npm-check is another tool for checking and updating outdated npm dependencies. It provides a more interactive experience compared to npm-check-updates, allowing you to see which dependencies are outdated, unused, or missing, and to update them interactively.

depcheck

depcheck is a tool that helps you find unused dependencies in your project. While it doesn't focus on updating dependencies, it complements npm-check-updates by identifying dependencies that are no longer needed.

README

v3 released! See the release notes for a description of breaking changes.

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

npm-check-updates maintains your existing semantic versioning policies, i.e., it will upgrade "express": "^4.0.0" to "express": "^5.0.0".

npm-check-updates only modifies your 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

--configFilePath         rc config file path (default: directory of `packageFile` or ./ otherwise)
--configFileName         rc config file name (default: .ncurc.{json,yml,js})                             
--cwd                    Used as current working directory for `spawn` in npm listing
--dep                    check only a specific section(s) of dependencies:
                         prod|dev|peer|optional|bundle (comma-delimited)
--engines-node           include only packages that satisfy engines.node as
                         specified in the package file
-e, --error-level        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)
-f, --filter             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
-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               Will return output like `jsonAll` but only lists
                         `dependencies`, `devDependencies`, and
                         `optionalDependencies` of the new package data.
--jsonUpgraded           output upgraded dependencies in json
-l, --loglevel           what level of logs to report: silent, error, warn,
                         info, verbose, silly (default: warn)
-m, --minimal            do not upgrade to newer versions that are already
                         satisfied by the existing version range (v2 behavior).
-n, --newest             find the newest published versions available instead
                         of the latest stable versions
-p, --packageManager     npm or bower (default: npm)
--packageData            include stringified package file (use stdin instead)
--packageFile            package file location (default: ./package.json)
--pre                    include -alpha, -beta, -rc. Default: 0. Default
                         with --newest and --greatest: 1.
--prefix                 Used as current working directory in bower and npm
-r, --registry           specify third-party NPM registry
--removeRange            remove version ranges from the final package version
-s, --silent             don't output anything (--loglevel silent)
--semverLevel            find the highest version within "major" or "minor"
-t, --greatest           find the highest versions available instead of the
                         latest stable versions
--timeout                a global timeout in ms
-u, --upgrade            overwrite package file
-v, --version            get version
-V                       get version
-x, --reject             exclude packages matching the given string, comma-
                         delimited list, or regex

How dependency updates are determined

• Direct dependencies will be increased to the latest stable version:
  • 2.0.1 → 2.2.0
  • 1.2 → 1.3
  • 0.1.0 → 1.0.1
  • with --semverLevel major
    • 0.1.0 → 0.2.1
  • with --semverLevel minor
    • 0.1.0 → 0.1.2
• Semantic versioning policies for levels are maintained while satisfying the latest version:
• ^1.2.0 → ^2.0.0
• 1.x → 2.x
• "Any version" is maintained:
  • * → *
• "Greater than" is maintained:
  • >0.2.0 → >0.3.0
• Closed ranges are replaced with a wildcard:
  • 1.0.0 < 2.0.0 → ^3.0.0

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 Use

npm-check-updates can be required:

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

ncu.run({
    // Any command-line option can be specified here.
    // These are set by default:
    jsonUpgraded: true,
    packageManager: 'npm',
    silent: true
}).then((upgraded) => {
    console.log('dependencies to upgrade:', upgraded);
});

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 -g --packageFile package.json. See #136.

Also search the issues page.

Problems?

Please file an issue! But always search existing issues first!