npm-check-updates — Find Newer Versions of Your Dependencies

Introduction

npm-check-updates (commonly called ncu) finds newer versions of dependencies than what your package.json currently allows. It respects semver ranges by default but can upgrade past them, giving you full control over when and how you update.

What npm-check-updates Does

• Scans package.json and reports all dependencies with newer versions available
• Upgrades version constraints in package.json to match the latest published versions
• Supports filtering by package name, dependency type, or semver level (major, minor, patch)
• Works with npm, yarn, pnpm, and bun lockfiles
• Provides interactive mode for selectively choosing which packages to upgrade

Architecture Overview

ncu reads your package.json, queries the npm registry (or a configured private registry) for the latest versions of each dependency, compares them against current constraints, and optionally rewrites package.json. It uses the npm registry API directly and does not require a local node_modules directory.

Self-Hosting & Configuration

• Install globally: npm install -g npm-check-updates, or run via npx
• Configure with .ncurc.js or .ncurc.json in your project root
• Set a default target version level: --target minor, --target patch, or --target latest
• Filter packages with --filter or --reject glob patterns
• Use --peer to include peerDependencies in the check

Key Features

• Interactive mode (--interactive) lets you pick which updates to apply one by one
• Doctor mode (--doctor) runs tests after each upgrade and reverts if they fail
• Supports monorepos: scan workspaces with --workspaces flag
• Group-by-major output shows which upgrades involve breaking changes
• Deep mode checks installed packages in addition to package.json declarations

Comparison with Similar Tools

• npm outdated — Built-in npm command showing outdated packages but cannot upgrade package.json automatically
• npm-check — Similar tool with an interactive UI; ncu is more focused on version bumping with deeper filtering
• Renovate — Automated bot that opens PRs; ncu is a local CLI for manual or CI-driven upgrades
• Dependabot — GitHub-integrated update service; ncu runs anywhere without requiring GitHub

FAQ

Q: Does ncu modify node_modules or the lockfile? A: No. ncu only modifies package.json. You run npm install (or yarn/pnpm) yourself afterward to update the lockfile and node_modules.

Q: Can I use ncu in CI to fail if dependencies are outdated? A: Yes. Run ncu with --errorLevel 2 and it exits with a non-zero code when upgradeable packages are found.

Q: How do I exclude specific packages from upgrades? A: Use --reject or add a reject list to your .ncurc.js config file.

Q: Does it work with private registries? A: Yes. ncu respects your .npmrc registry configuration and supports custom registry URLs via the --registry flag.

Sources

• https://github.com/raineorshine/npm-check-updates
• https://www.npmjs.com/package/npm-check-updates