npm-check-updates upgrades your package.json dependencies to the latest versions, ignoring specified versions.
- maintains existing semantic versioning policies, i.e.
"react": "^17.0.2"
to"react": "^18.3.1"
. - only modifies package.json file. Run
npm install
to update your installed packages and package-lock.json. - sensible defaults, but highly customizable
- compatible with npm, yarn, pnpm, deno, and bun
- CLI and module usage
Install globally to use npm-check-updates
or the shorter ncu
:
npm install -g npm-check-updates
Or run with npx (only the long form is supported):
npx npm-check-updates
Check the latest versions of all project dependencies:
$ 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
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
Choose which packages to update in interactive mode:
ncu --interactive
ncu -i
Combine with --format group
for a truly luxe experience:
Filter packages using the --filter
option or adding additional cli arguments:
# upgrade only mocha
ncu mocha
ncu -f mocha
ncu --filter mocha
# upgrade only chalk, mocha, and react
ncu chalk mocha react
ncu chalk, mocha, react
ncu -f "chalk mocha react"
Filter with wildcards or regex:
# upgrade packages that start with "react-"
ncu react-*
ncu "/^react-.*$/"
Exclude specific packages with the --reject
option or prefixing a filter with !
. Supports strings, wildcards, globs, comma-or-space-delimited lists, and regex:
# upgrade everything except nodemon
ncu \!nodemon
ncu -x nodemon
ncu --reject nodemon
# upgrade packages that do not start with "react-".
ncu \!react-*
ncu '/^(?!react-).*$/' # mac/linux
ncu "/^(?!react-).*$/" # windows
Advanced filters: filter, filterResults, filterVersion
- 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:
*
→*
- Prerelease versions are ignored by default.
- Use
--pre
to include prerelease versions (e.g.alpha
,beta
,build1235
)
- Use
- Choose what level to upgrade to:
- With
--target semver
, update according to your specified semver version ranges:^1.1.0
→^1.9.99
- With
--target minor
, strictly update the patch and minor versions (including major version zero):0.1.0
→0.2.1
- With
--target patch
, strictly update the patch version (including major version zero):0.1.0
→0.1.2
- With
--target @next
, update to the version published on thenext
tag:0.1.0
->0.1.1-next.1
- With
Options are merged with the following precedence:
- Command line options
- Local Config File
- Project Config File
- User Config File
Options that take no arguments can be negated by prefixing them with --no-
, e.g. --no-peer
.
--cache | Cache versions to a local cache file. Default --cacheFile is ~/.ncu-cache.json and default --cacheExpiration is 10 minutes. |
--cacheClear | Clear the default cache, or the cache file specified by --cacheFile . |
--cacheExpiration <min> | Cache expiration in minutes. Only works with --cache . (default: 10) |
--cacheFile <path> | Filepath for the cache file. Only works with --cache . (default: "~/.ncu-cache.json") |
--color | Force color in terminal. |
--concurrency <n> | Max number of concurrent HTTP requests to registry. (default: 8) |
--configFileName <s> | Config file name. (default: .ncurc.{json,yml,js,cjs}) |
--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, or packageManager (comma-delimited). (default: ["prod","dev","optional","packageManager"]) |
--deprecated | Include deprecated packages. Use --no-deprecated to exclude deprecated packages (uses more bandwidth). (default: true) |
-d, --doctor | Iteratively installs upgrades and runs tests to identify breaking upgrades. Requires -u to execute. |
--doctorInstall <command> | Specifies the install script to use in doctor mode. (default: npm install or the equivalent for your package manager) |
--doctorTest <command> | Specifies the test script to use in doctor mode. (default: npm test ) |
--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 <p> | Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. |
filterResults <fn> | Filters out upgrades based on a user provided function. |
--filterVersion <p> | Filter on package version using comma-or-space-delimited list, /regex/, or predicate function. |
--format <value> | Modify the output formatting or show additional information. Specify one or more comma-delimited values: group, ownerChanged, repo, time, lines, installedVersion. (default: []) |
-g, --global | Check global packages instead of in the current project. |
groupFunction <fn> | Customize how packages are divided into groups when using --format group . |
--install <value> | Control the auto-install behavior: always, never, prompt. (default: "prompt") |
-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") |
--mergeConfig | Merges nested configs with the root config file for --deep or --packageFile options. (default: false) |
-m, --minimal | Do not upgrade newer versions that are already satisfied by the version range according to semver. |
--packageData <value> | Package file data (you can also use stdin). |
--packageFile <path|glob> | Package file(s) location. (default: ./package.json) |
-p, --packageManager <s> | npm, yarn, pnpm, deno, bun, staticRegistry (default: npm). |
--peer | Check peer dependencies of installed packages and filter updates to compatible versions. |
--pre <n> | Include prerelease versions, e.g. -alpha.0, -beta.5, -rc.2. Automatically set to 1 when --target is newest or greatest, or when the current version is a prerelease. (default: 0) |
--prefix <path> | Current working directory of npm. |
-r, --registry <uri> | Specify the registry to use when looking up package versions. |
--registryType <type> | Specify whether --registry refers to a full npm registry or a simple JSON file or url: npm, json. (default: npm) |
-x, --reject <p> | Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. |
--rejectVersion <p> | Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function. |
--removeRange | Remove version ranges from the final package version. |
--retry <n> | Number of times to retry failed requests for package info. (default: 3) |
--root | Runs updates on the root project in addition to specified workspaces. Only allowed with --workspace or --workspaces . (default: true) |
-s, --silent | Don't output anything. Alias for --loglevel silent. |
--stdin | Read package.json from stdin. |
-t, --target <value> | Determines the version to upgrade to: latest, newest, greatest, minor, patch, semver, @[tag] |
--timeout <ms> | Global timeout in milliseconds. (default: no global timeout and 30 seconds per npm-registry-fetch) |
-u, --upgrade | Overwrite package file with upgraded versions instead of just outputting to console. |
--verbose | Log additional information for debugging. Alias for --loglevel verbose. |
-w, --workspace <s> | Run on one or more specified workspaces. Add --root to also upgrade the root project. (default: []) |
-ws, --workspaces | Run on all workspaces. Add --root to also upgrade the root project. |
Some options have advanced usage, or allow per-package values by specifying a function in your .ncurc.js file.
Run ncu --help [OPTION]
to view advanced help for a specific option, or see below:
Usage:
ncu --doctor -u
ncu --no-doctor
ncu -du
Iteratively installs upgrades and runs your project's tests to identify breaking upgrades. Reverts broken upgrades and updates package.json with working upgrades.
Requires -u
to execute (modifies your package file, lock file, and node_modules)
To be more precise:
- Runs
npm install
andnpm test
to ensure tests are currently passing. - Runs
ncu -u
to optimistically upgrade all dependencies. - If tests pass, hurray!
- If tests fail, restores package file and lock file.
- For each dependency, install upgrade and run tests.
- Prints broken upgrades with test error.
- Saves working upgrades to package.json.
Additional options:
--doctorInstall | specify a custom install script (default: `npm install` or `yarn`) |
--doctorTest | specify a custom test script (default: `npm test`) |
Example:
$ 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
Usage:
ncu --filter [p]
ncu -f [p]
Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. Only included packages will be checked with --peer
.
--filter
runs before new versions are fetched, in contrast to --filterResults
which runs after.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
/**
@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
}
Filters out upgrades based on a user provided function.
filterResults
runs after new versions are fetched, in contrast to filter
, reject
, filterVersion
, and rejectVersion
, which run before. This allows you to filter out upgrades with filterResults
based on how the version has changed (e.g. a major version change).
Only available in .ncurc.js or when importing npm-check-updates as a module.
/** 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
}
For the SemVer type definition, see: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring
Usage:
ncu --filterVersion [p]
Include only versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the filter option function.
/**
@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
}
Usage:
ncu --format [value]
Modify the output formatting or show additional information. Specify one or more comma-delimited values.
group | Groups packages by major, minor, patch, and major version zero updates. |
ownerChanged | Shows if the package owner has changed. |
repo | Infers and displays links to the package's source code repository. Requires packages to be installed. |
time | Shows the publish time of each upgrade. |
lines | Prints name@version on separate lines. Useful for piping to npm install. |
installedVersion | Prints the exact current version number instead of a range. |
Customize how packages are divided into groups when using --format group
.
Only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
/**
@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
}
Usage:
ncu --install [value]
Default: prompt
Control the auto-install behavior.
always | Runs your package manager's install command automatically after upgrading. |
never | Does not install and does not prompt. |
prompt | Shows a message after upgrading that recommends an install, but does not install. In interactive mode, prompts for install. (default) |
Usage:
ncu --packageManager [s]
ncu -p [s]
Specifies the package manager to use when looking up versions.
npm | System-installed npm. Default. |
yarn | System-installed yarn. Automatically used if yarn.lock is present. |
pnpm | System-installed pnpm. Automatically used if pnpm-lock.yaml is present. |
bun | System-installed bun. Automatically used if bun.lockb is present. |
Usage:
ncu --peer
ncu --no-peer
Check peer dependencies of installed packages and filter updates to compatible versions.
Example:
The following example demonstrates how --peer
works, and how it uses peer dependencies from upgraded modules.
The package ncu-test-peer-update has two versions published:
- 1.0.0 has peer dependency
"ncu-test-return-version": "1.0.x"
- 1.1.0 has peer dependency
"ncu-test-return-version": "1.1.x"
Our test app has the following dependencies:
"ncu-test-peer-update": "1.0.0",
"ncu-test-return-version": "1.0.0"
The latest versions of these packages are:
"ncu-test-peer-update": "1.1.0",
"ncu-test-return-version": "2.0.0"
With --peer
:
ncu upgrades packages to the highest version that still adheres to the peer dependency constraints:
ncu-test-peer-update 1.0.0 → 1.1.0
ncu-test-return-version 1.0.0 → 1.1.0
Without --peer
:
As a comparison: without using the --peer
option, ncu will suggest the latest versions, ignoring peer dependencies:
ncu-test-peer-update 1.0.0 → 1.1.0
ncu-test-return-version 1.0.0 → 2.0.0
Usage:
ncu --registryType [type]
Specify whether --registry
refers to a full npm registry or a simple JSON file.
npm | Default npm registry |
json | Checks versions from a file or url to a simple JSON registry. Must include the `--registry` option.
Example:
registry.json:
|
Usage:
ncu --reject [p]
ncu -x [p]
The inverse of --filter
. Exclude package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. This will also exclude them from the --peer
check.
--reject
runs before new versions are fetched, in contrast to --filterResults
which runs after.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
/**
@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
}
Usage:
ncu --rejectVersion [p]
The inverse of --filterVersion
. Exclude versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the reject option function.
/**
@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
}
Usage:
ncu --target [value]
ncu -t [value]
Determines the version to upgrade to. (default: "latest")
greatest | Upgrade to the highest version number published, regardless of release date or tag. Includes prereleases. |
latest | Upgrade to whatever the package's "latest" git tag points to. Excludes prereleases unless --pre is specified. |
minor | Upgrade to the highest minor version without bumping the major version. |
newest | Upgrade to the version with the most recent publish date, even if there are other version numbers that are higher. Includes prereleases. |
patch | Upgrade to the highest patch version without bumping the minor or major versions. |
semver | Upgrade to the highest version within the semver range specified in your package.json. |
@[tag] | Upgrade to the version published to a specific tag, e.g. 'next' or 'beta'. |
You can also specify a custom function in your .ncurc.js file, or when importing npm-check-updates as a module:
/** 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'
}
Use a .ncurc.{json,yml,js,cjs}
file to specify configuration information.
You can specify the file name and path using --configFileName
and --configFilePath
command line options.
For example, .ncurc.json
:
{
"upgrade": true,
"filter": "svelte",
"reject": ["@types/estree", "ts-node"]
}
If you write .ncurc
config files using json or yaml, you can add the JSON Schema to your IDE settings for completions.
e.g. for VS Code:
"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",
]
},
npm-check-updates can be imported as a module:
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", ... }
Contributions are happily accepted. I respond to all PR's and can offer guidance on where to make changes. For contributing tips see CONTRIBUTING.md.
File an issue. Please search existing issues first.