npm-check-updates: Master Your JavaScript Dependencies

In short: As of September 5, 2026, use npm-check-updates to choose and write new versions to package.json, then use your package manager to install and lock them. Prefer npm outdated for a simple diagnosis. For major upgrades, process one dependency at a time and validate every change with tests.

npm update respects the semver constraints already declared. npm-check-updates, or ncu, serves a different need: finding versions beyond those constraints and explicitly preparing their adoption.

npm-check-updates or npm outdated: which should you choose?

The tools complement each other. They are not interchangeable.

Command	Main purpose	Changes the project
npm outdated	Compare installed, “wanted,” and “latest” versions	No
npm update	Install versions allowed by current constraints	Yes, within semver limits
ncu	Show possible new versions for package.json	No
ncu -u	Rewrite versions declared in package.json	Yes, without installing

The official npm documentation explains that npm outdated distinguishes the installed version, the highest version compatible with the constraint, and the version associated with the latest tag. The npm-check-updates documentation states that ncu ignores currently declared version numbers while preserving their semver policy, such as the ^ operator.

How do you run ncu without installing it?

The simplest npm form uses the full package name:

npx npm-check-updates

You can also install it globally:

npm install -g npm-check-updates
ncu

By default, the command only displays suggestions. Add -u to rewrite package.json:

ncu -u
npm install
npm test

This separation matters. ncu -u prepares the declarations; npm install resolves versions and updates node_modules and the lockfile. Review the diff before committing it.

How do you limit the upgrade level?

The --target option avoids upgrading everything to its latest version:

# Patches only
ncu --target patch

# Minor versions and patches, without changing the major
ncu --target minor

# Stay within the declared semver constraints
ncu --target semver

Under the Semantic Versioning specification, a major version signals incompatible changes to the public API. This convention guides your review, but it does not replace release notes or project tests.

How do you select dependencies to update?

Interactive mode is useful for manual selection:

ncu --interactive

To include or exclude packages in a script, use filters:

# Target React and React DOM
ncu -u --filter "react react-dom"

# Exclude TypeScript and ESLint
ncu -u --reject "typescript eslint"

You can also limit the search to specific package.json sections:

ncu --dep prod
ncu --dep dev

How do you complete a major upgrade safely?

A major upgrade deserves an isolated change. The recommended workflow is deliberately simple:

# Inspect one dependency
ncu --filter express

# Update its declaration
ncu -u --filter express

# Install, then verify the project
npm install
npm test

Then read the package’s migration guide and inspect the lockfile diff. Avoid mixing several major migrations: if a test fails, you will identify the cause faster.

For automated analysis, doctor mode installs upgrades and runs tests to identify those that break the project:

ncu --doctor -u --doctorInstall "npm install" --doctorTest "npm test"

This mode also changes the lockfile and node_modules. Run it only from a clean, version-controlled state.

How do you reduce the risk of very recent releases?

The --cooldown option sets a minimum age for suggested versions:

ncu --cooldown 7d

According to the official ncu documentation, this option reduces the risk of immediately adopting a newly published version. It is not a security analysis, however: keep your audits, change review, and tests.

How do you use npm-check-updates in CI?

To fail a step when updates are detected, use the error level intended for continuous integration:

npx npm-check-updates --errorLevel 2

The command remains read-only unless you add -u. CI can therefore report version gaps without rewriting package.json.

In a monorepo, ncu can also scan workspaces:

npx npm-check-updates --workspaces --errorLevel 2

I recommend using this check as information or as a scheduled policy, rather than blocking every contribution as soon as a new version is published. An available dependency is not always a dependency you should adopt immediately.

What workflow should you use day to day?

The most reliable strategy separates each step clearly:

1. Run ncu to review the gaps.
2. Apply patches and minor versions first.
3. Install the dependencies and run the tests.
4. Process each major version separately.
5. Commit package.json and the lockfile together.

npm-check-updates is not a risk-free upgrade button. It is a decision tool that makes changes visible and controllable. For an actively maintained project, I prefer it to manually editing package.json, while keeping npm outdated for quick diagnostics.

Sources

• npm-check-updates — official documentation
• npm outdated — npm documentation
• npm update — npm documentation
• Semantic Versioning 2.0.0