| --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 or .ncurc.{json,yaml,yml,js,mjs,cjs}) |
| --configFilePath <path> |
Directory of .ncurc config file. (default: directory of packageFile) |
| -c, --cooldown <period> |
Sets a minimum age for package versions to be considered for upgrade. Accepts a number (days) or a string with a unit: "7d" (days), "12h" (hours), "30m" (minutes). Reduces the risk of installing newly published, potentially compromised packages. |
| --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 (20–25% slower). (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 results based on a user provided predicate function after fetching new versions. |
| --filterVersion <p> |
Filter on package version using comma-or-space-delimited list or /regex/. |
| --format <value> |
Modify the output formatting or show additional information. Specify one or more comma-delimited values: dep, group, ownerChanged, repo, time, lines, installedVersion, cooldown. group is the only value included by default; use --format no-group to disable it. (default: ["group"]) |
| -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 or /regex/. |
| --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], or [function]. (default: latest) |
| --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. |
| --workspace <s> |
Run on one or more specified workspaces. Add --no-root to exclude the root project. (default: []) |
| -w, --workspaces |
Run on all workspaces. Add --no-root to exclude the root project. |
## Advanced Options
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:
## cooldown
Usage:
ncu --cooldown [period]
ncu -c [period]
The cooldown option helps protect against supply chain attacks by requiring package versions to be published at least the given amount of time before considering them for upgrade.
The value can be a plain number (days) or a string with a unit suffix:
--cooldown 7 7 days
--cooldown 7d 7 days (same as above)
--cooldown 12h 12 hours
--cooldown 30m 30 minutes
With the default `--target latest`, if the latest dist-tag version is within the cooldown window, ncu falls back to the greatest version that passes the cooldown threshold. To instead skip the package entirely (strict behaviour), use `--target "@latest"`.
Example:
Let's examine how cooldown works with a package that has these versions available:
1.0.0 Released 7 days ago (initial version)
1.1.0 Released 6 days ago (minor update)
1.1.1 Released 5 days ago (patch update)
1.2.0 Released 5 days ago (minor update)
2.0.0-beta.1 Released 5 days ago (beta release)
1.2.1 Released 4 days ago (patch update)
1.3.0 Released 4 days ago (minor update) [latest]
2.0.0-beta.2 Released 3 days ago (beta release)
2.0.0-beta.3 Released 2 days ago (beta release) [beta]
With default target (latest):
```js
$ ncu --cooldown 5
```
Falls back to 1.2.0 because:
- Latest version (1.3.0) is only 4 days old (within 5-day cooldown)
- 1.2.0 is the greatest version that is at least 5 days old
With `@latest` strict target:
```js
$ ncu --cooldown 5 --target @latest
```
No update will be suggested because:
- Latest version (1.3.0) is only 4 days old
- Cooldown requires versions to be at least 5 days old
- `@latest` is strict: no fallback to older versions
With `@beta`/`@tag` target:
```js
$ ncu --cooldown 3 --target @beta
```
No update will be suggested because:
- Current beta (2.0.0-beta.3) is only 2 days old
- Cooldown requires versions to be at least 3 days old
- Use `--cooldown 2` or lower to allow this update
With other targets:
```js
$ ncu --cooldown 5 --target greatest|newest|minor|patch|semver
```
Each target will select the best version that is at least 5 days old:
greatest → 1.2.0 (highest version number outside cooldown)
newest → 2.0.0-beta.1 (most recently published version outside cooldown)
minor → 1.2.0 (highest minor version outside cooldown)
patch → 1.1.1 (highest patch version outside cooldown)
You can also provide a custom function in your .ncurc.js file or when importing npm-check-updates as a module.
> :warning: The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. To convert a JSON config to a JS config, follow the instructions at https://github.com/raineorshine/npm-check-updates#config-functions.
```js
/** Set cooldown to 3 days but skip it for `@my-company` packages.
@param packageName The name of the dependency.
@returns Cooldown days restriction for given package.
*/
cooldown: packageName => (packageName.startsWith('@my-company') ? 0 : 3)
```
### Package Manager Configurations
If `--cooldown` is not set explicitly, `ncu` automatically reads the cooldown configuration from your package manager's own native config — each package manager only consults its own config and these are not cross-applied between package managers: