npm-check-updates

• maintains existing semantic versioning policies, i.e. "react": "^16.0.4" to "react": "^18.2.0".
• only modifies package.json file. Run npm install to update your installed packages and package-lock.json.
• sensible defaults, but highly customizable
• CLI and module usage
• compatible with: npm, yarn, pnpm, deno, bun

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

Installation

npm install -g npm-check-updates

npx npm-check-updates

Usage

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

 eslint             7.32.0  →    8.0.0
 prettier           ^2.7.1  →   ^3.0.0
 svelte            ^3.48.0  →  ^3.51.0
 typescript         >3.0.0  →   >4.0.0
 untildify          <4.0.0  →   ^4.0.0
 webpack               4.x  →      5.x

Run ncu -u to upgrade package.json

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

ncu -g

Interactive Mode

ncu --interactive
ncu -i

Filter packages

# 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:

• Range operators are preserved and the version is updated:

• "Less than" is replaced with a wildcard:

• "Any version" is preserved:

• Prerelease and deprecated versions are ignored by default.

• With --target minor, only update patch and minor:

• With --target patch, only update patch:

• With --target @next, update to the version published on the next tag:

Options

1. CLI
2. Local Config File
3. Project Config File
4. User Config File

<td>--cache</td>
<td>Cache versions to a local cache file. Default <code>--cacheFile</code> is ~/.ncu-cache.json and default <code>--cacheExpiration</code> is 10 minutes.</td>

<td>--cacheClear</td>
<td>Clear the default cache, or the cache file specified by <code>--cacheFile</code>.</td>

<td>--cacheExpiration <min></td>
<td>Cache expiration in minutes. Only works with <code>--cache</code>. (default: 10)</td>

<td>--cacheFile <path></td>
<td>Filepath for the cache file. Only works with <code>--cache</code>. (default: "~/.ncu-cache.json")</td>

<td>--color</td>
<td>Force color in terminal.</td>

<td>--concurrency <n></td>
<td>Max number of concurrent HTTP requests to registry. (default: 8)</td>

<td>--configFileName <s></td>
<td>Config file name. (default: .ncurc.{json,yml,js,cjs})</td>

<td>--configFilePath <path></td>
<td>Directory of .ncurc config file. (default: directory of <code>packageFile</code>)</td>

<td>--cwd <path></td>
<td>Working directory in which npm will be executed.</td>

<td>--deep</td>
<td>Run recursively in current working directory. Alias of (<code>--packageFile '**/package.json'<code>).</td>

<td>--dep <value></td>
<td>Check one or more sections of dependencies only: dev, optional, peer, prod, or packageManager (comma-delimited). (default: ["prod","dev","optional"])</td>

<td>--deprecated</td>
<td>Include deprecated packages.</td>

<td><a href="#doctor">-d, --doctor</a></td>
<td>Iteratively installs upgrades and runs tests to identify breaking upgrades. Requires <code>-u</code> to execute.</td>

<td>--doctorInstall <command></td>
<td>Specifies the install script to use in doctor mode. (default: <code>npm install</code> or the equivalent for your package manager)</td>

<td>--doctorTest <command></td>
<td>Specifies the test script to use in doctor mode. (default: <code>npm test</code>)</td>

<td>--enginesNode</td>
<td>Include only packages that satisfy engines.node as specified in the package file.</td>

<td>-e, --errorLevel <n></td>
<td>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)</td>

<td><a href="#filter">-f, --filter <p></a></td>
<td>Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.</td>

<td><a href="#filterresults">filterResults <fn></a></td>
<td>Filters out upgrades based on a user provided function.</td>

<td><a href="#filterversion">--filterVersion <p></a></td>
<td>Filter on package version using comma-or-space-delimited list, /regex/, or predicate function.</td>

<td><a href="#format">--format <value></a></td>
<td>Modify the output formatting or show additional information. Specify one or more comma-delimited values: group, ownerChanged, repo, time, lines. (default: [])</td>

<td>-g, --global</td>
<td>Check global packages instead of in the current project.</td>

<td><a href="#groupfunction">groupFunction <fn></a></td>
<td>Customize how packages are divided into groups when using <code>--format group</code>.</td>

<td><a href="#install">--install <value></a></td>
<td>Control the auto-install behavior: always, never, prompt. (default: "prompt")</td>

<td>-i, --interactive</td>
<td>Enable interactive prompts for each dependency; implies <code>-u</code> unless one of the json options are set.</td>

<td>-j, --jsonAll</td>
<td>Output new package file instead of human-readable message.</td>

<td>--jsonDeps</td>
<td>Like <code>jsonAll</code> but only lists <code>dependencies</code>, <code>devDependencies</code>, <code>optionalDependencies</code>, etc of the new package data.</td>

<td>--jsonUpgraded</td>
<td>Output upgraded dependencies in json.</td>

<td>-l, --loglevel <n></td>
<td>Amount to log: silent, error, minimal, warn, info, verbose, silly. (default: "warn")</td>

<td>--mergeConfig</td>
<td>Merges nested configs with the root config file for <code>--deep</code> or <code>--packageFile</code> options. (default: false)</td>

<td>-m, --minimal</td>
<td>Do not upgrade newer versions that are already satisfied by the version range according to semver.</td>

<td>--packageData <value></td>
<td>Package file data (you can also use stdin).</td>

<td>--packageFile <path|glob></td>
<td>Package file(s) location. (default: ./package.json)</td>

<td><a href="#packagemanager">-p, --packageManager <s></a></td>
<td>npm, yarn, pnpm, deno, bun, staticRegistry (default: npm).</td>

<td><a href="#peer">--peer</a></td>
<td>Check peer dependencies of installed packages and filter updates to compatible versions.</td>

<td>--pre <n></td>
<td>Include prerelease versions, e.g. -alpha.0, -beta.5, -rc.2. Automatically set to 1 when <code>--target</code> is newest or greatest, or when the current version is a prerelease. (default: 0)</td>

<td>--prefix <path></td>
<td>Current working directory of npm.</td>

<td>-r, --registry <uri></td>
<td>Specify the registry to use when looking up package versions.</td>

<td><a href="#registrytype">--registryType <type></a></td>
<td>Specify whether --registry refers to a full npm registry or a simple JSON file or url: npm, json. (default: npm)</td>

<td><a href="#reject">-x, --reject <p></a></td>
<td>Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.</td>

<td><a href="#rejectversion">--rejectVersion <p></a></td>
<td>Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function.</td>

<td>--removeRange</td>
<td>Remove version ranges from the final package version.</td>

<td>--retry <n></td>
<td>Number of times to retry failed requests for package info. (default: 3)</td>

<td>--root</td>
<td>Runs updates on the root project in addition to specified workspaces. Only allowed with <code>--workspace</code> or <code>--workspaces</code>. (default: false)</td>

<td>-s, --silent</td>
<td>Don't output anything. Alias for <code>--loglevel</code> silent.</td>

<td>--stdin</td>
<td>Read package.json from stdin.</td>

<td><a href="#target">-t, --target <value></a></td>
<td>Determines the version to upgrade to: latest, newest, greatest, minor, patch, semver, @[tag], or [function]. (default: latest)</td>

<td>--timeout <ms></td>
<td>Global timeout in milliseconds. (default: no global timeout and 30 seconds per npm-registry-fetch)</td>

<td>-u, --upgrade</td>
<td>Overwrite package file with upgraded versions instead of just outputting to console.</td>

<td>--verbose</td>
<td>Log additional information for debugging. Alias for <code>--loglevel</code> verbose.</td>

<td>-w, --workspace <s></td>
<td>Run on one or more specified workspaces. Add <code>--root</code> to also upgrade the root project. (default: [])</td>

<td>-ws, --workspaces</td>
<td>Run on all workspaces. Add <code>--root</code> to also upgrade the root project.</td>

Advanced Options

doctor

ncu --doctor
ncu --no-doctor
ncu -d

$ ncu --doctor -u
Running tests before upgrading
npm install
npm run test
Upgrading all dependencies and re-running tests
ncu -u
npm install
npm run test
Tests failed
Identifying broken dependencies
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

/projects/myproject/test.js:13
  throw new Error('Test failed!')
  ^

npm install --no-save react-dnd@11.1.3
npm run test
  ✓ react-dnd 10.0.0 → 11.1.3
Saving partially upgraded package.json

ncu --filter [p]
ncu -f [p]

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be included, false if it should be excluded.
*/
filterFunction: (name, semver) => {
  if (name.startsWith('@myorg/')) {
    return false
  }
  return true
}

/** Filter out non-major version updates.
  @param {string} packageName        The name of the dependency.
  @param {string} current            Current version declaration (may be a range).
  @param {SemVer[]} currentSemver    Current version declaration in semantic versioning format (may be a range).
  @param {string} upgraded           Upgraded version.
  @param {SemVer} upgradedSemver     Upgraded version in semantic versioning format.
  @returns {boolean}                 Return true if the upgrade should be kept, otherwise it will be ignored.
*/
filterResults: (packageName, { current, currentSemver, upgraded, upgradedSemver }) => {
  const currentMajor = parseInt(currentSemver[0]?.major, 10)
  const upgradedMajor = parseInt(upgradedSemver?.major, 10)
  if (currentMajor && upgradedMajor) {
    return currentMajor < upgradedMajor
  }
  return true
}

ncu --filterVersion [p]

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be included, false if it should be excluded.
*/
filterVersionFunction: (name, semver) => {
  if (name.startsWith('@myorg/') && parseInt(semver[0]?.major) > 5) {
    return false
  }
  return true
}

ncu --format [value]

/**
  @param name             The name of the dependency.
  @param defaultGroup     The predefined group name which will be used by default.
  @param currentSpec      The current version range in your package.json.
  @param upgradedSpec     The upgraded version range that will be written to your package.json.
  @param upgradedVersion  The upgraded version number returned by the registry.
  @returns                A predefined group name ('major' | 'minor' | 'patch' | 'majorVersionZero' | 'none') or a custom string to create your own group.
*/
groupFunction: (name, defaultGroup, currentSpec, upgradedSpec, upgradedVersion) => {
  if (name === 'typescript' && defaultGroup === 'minor') {
    return 'major'
  }
  if (name.startsWith('@myorg/')) {
    return 'My Org'
  }
  return defaultGroup
}

ncu --install [value]

ncu --packageManager [s]
ncu -p [s]

ncu --peer
ncu --no-peer

"ncu-test-peer-update": "1.0.0",
"ncu-test-return-version": "1.0.0"

"ncu-test-peer-update": "1.1.0",
"ncu-test-return-version": "2.0.0"

ncu-test-peer-update     1.0.0  →  1.1.0
ncu-test-return-version  1.0.0  →  1.1.0

ncu-test-peer-update     1.0.0  →  1.1.0
ncu-test-return-version  1.0.0  →  2.0.0

ncu --registryType [type]

// local file
$ ncu --registryType json --registry ./registry.json

// url
$ ncu --registryType json --registry https://api.mydomain/registry.json

// you can omit --registryType when the registry ends in .json
$ ncu --registry ./registry.json
$ ncu --registry https://api.mydomain/registry.json

{
  "prettier": "2.7.1",
  "typescript": "4.7.4"
}

ncu --reject [p]
ncu -x [p]

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be excluded, false if it should be included.
*/
rejectFunction: (name, semver) => {
  if (name.startsWith('@myorg/')) {
    return true
  }
  return false
}

ncu --rejectVersion [p]

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be excluded, false if it should be included.
*/
rejectVersionFunction: (name, semver) => {
  if (name.startsWith('@myorg/') && parseInt(semver[0]?.major) > 5) {
    return true
  }
  return false
}

ncu --target [value]
ncu -t [value]

/** Upgrade major version zero to the next minor version, and everything else to latest.
  @param name     The name of the dependency.
  @param semver   A parsed Semver object of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        One of the valid target values (specified in the table above).
*/
target: (name, semver) => {
  if (parseInt(semver[0]?.major) === '0') return 'minor'
  return 'latest'
}

Config File

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

"json.schemas": [
  {
    "fileMatch": [
      ".ncurc",
      ".ncurc.json",
    ],
    "url": "https://raw.githubusercontent.com/raineorshine/npm-check-updates/main/src/types/RunOptions.json"
  }
],
"yaml.schemas": {
  "https://raw.githubusercontent.com/raineorshine/npm-check-updates/main/src/types/RunOptions.json": [
      ".ncurc.yml",
  ]
},

Module/Programmatic Usage

import ncu from 'npm-check-updates'

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

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

Contributing

Problems?