npm Cheatsheet - Node.js Package Manager Reference

A Node project is only as reproducible as your dependency commands. This reference runs the whole lifecycle: init/scaffold, install/update/remove, version ranges and package-lock, npm scripts and npx, npm ls/audit/outdated for health, publishing, and config/cache handles. Compare to a bare command list, it also flags lockfile and audit subtleties that bite teams. Use it when CI fails on dependency resolution or a package won't install at the expected version. After reading you operate dependencies and debug install issues with intent.

Languages·41 commands·Last updated 2026-07-21

Typical Use Case

For developers managing Node.js projects with npm. This sheet clarifies the four easily-confused areas: the difference between npm install and npm ci (the former rewrites the lock file, CI must use the latter), how npm run relates to the npm start and npm test shorthands, what -D and -g change about scope, and using npx to avoid global installs. npm ls --depth=0 and npm why are also the proper route to diagnosing phantom dependencies and version conflicts, rather than repeatedly deleting node_modules.

Project Init 4

npm init -y

Quick package.json (defaults)

npm init

Interactive package.json

npm init <initializer> [args]

Scaffold a project (e.g. npm init vite)

npm create <initializer>@latest

create is an alias of init, like npx create-<init>

Install & Uninstall 7

npm install

Install all deps from package.json

npm install <pkg>

Install into dependencies

npm install -D <pkg>

Install into devDependencies

npm install -g <pkg>

Install globally

npm install <pkg> --save-exact

Pin exact version (-E)

npm uninstall <pkg>

Uninstall a dependency

npm uninstall -g <pkg>

Uninstall a global package

Version Management 6

npm install <pkg>@1.2.3

Install a specific version

npm install <pkg>@latest

Install/update to latest

npm install <pkg>@^1.0.0

Install by semver range (^, minor upgrades)

npm update [pkg]

Update deps within semver

npm outdated

List outdated deps (current/wanted/latest)

npm dedupe

Dedupe the dependency tree

Scripts & Run 6

npm run <script>

Run a script

npm start

Run the start script

npm test

Run the test script

npm run

List all scripts

npx <command> [args]

Run a package without installing (npx)

npm run <script> -- --port 8080

Pass args after -- to the script

Dependency Inspection 6

npm ls

View the dependency tree

npm ls --depth=0

Top-level deps only

npm ls <pkg>

Check if a package is installed

npm why <pkg>

Why a dependency is present (npm 7+)

npm audit

Audit for vulnerabilities

npm audit fix

Auto-fix vulnerabilities

Publish & Release 5

npm version <patch|minor|major>

Bump version and git tag

npm publish

Publish to the registry

npm publish --tag beta

Publish under a dist-tag (e.g. beta)

npm deprecate <pkg>@<ver> "reason"

Deprecate a version

npm owner add <user> [<pkg>]

Add a package owner

Config & Cache 7

npm config get registry

Show the current registry

npm config set registry https://registry.npmmirror.com

Switch to the npmmirror registry

npm config set <key> <value>

Set a config key (.npmrc)

npm config list

List all config

npm cache clean --force

Clean the npm cache

npm cache verify

Verify and clean cache

npm ci

Clean install from lockfile (CI/CD)

Parameter matrix

Parameter	Effect	Example
`init -y`	Quickly generate package.json with default values	`npm init -y`
`init <initializer>`	Scaffold a project with an initializer	`npm init vite`
`install <pkg>`	Install into dependencies	`npm install express`
`-D`	Install into devDependencies (build-time dependencies)	`npm install -D typescript`
`-g`	Global install	`npm install -g pnpm`
`--save-exact / -E`	Lock the exact version, without the ^	`npm install pkg --save-exact`
`pkg@1.2.3 / @latest`	Specify a version / the latest version	`npm install pkg@1.2.3`
`update`	Update to the latest version allowed by semver	`npm update`
`dedupe`	Deduplicate the dependency tree to reduce duplicate installs	`npm dedupe`
`run <script>`	Run a script in scripts	`npm run build`
`npx`	Run a package temporarily without a global install	`npx create-react-app my-app`
`run <s> -- --arg`	Pass arguments through to the script with --	`npm run dev -- --port 8080`
`ls --depth=0`	Show only top-level direct dependencies	`npm ls --depth=0`
`why <pkg>`	Trace which package pulled in a dependency	`npm why lodash`
`ci`	Clean install from the lock; recommended for CI	`npm ci`
`config set registry`	Switch the registry mirror	`npm config set registry https://registry.npmmirror.com`

Common pitfalls

SymptomIt runs fine locally, but installing dependencies in CI reports version mismatches.

Causepackage-lock.json was not committed or is out of date, so CI resolved different versions on its own.

FixCommit package-lock.json, and have CI switch to npm ci (installs strictly from the lock and clears node_modules first).

SymptomA package imported in the code works locally, but reports module not found after deployment.

CauseThat package was installed as a devDependency and skipped during npm ci --omit=dev or a production install.

FixPackages genuinely needed at runtime must go in dependencies; only build-time tooling belongs in devDependencies.

SymptomAfter npm audit fix, many dependencies jump major versions and the code breaks everywhere.

Causeaudit fix may introduce breaking updates, especially across major versions.

FixTry it on a branch and run the tests first; be cautious with --force in production and upgrade the affected packages manually one by one.

Symptomnpm install hangs on downloading or reports network errors.

CauseThe default registry is overseas and the network cannot reach it.

FixRun npm config set registry https://registry.npmmirror.com to switch mirrors; in enterprise environments, configure the internal source.

SymptomThe same package appears in the dependency tree in several different versions.

CauseThe semver ranges of the dependencies are incompatible, so npm installs a copy for each.

FixUse npm ls <pkg> to see how many copies there are; dedupe with npm dedupe, or force a single version with npm overrides.

SymptomAfter passing arguments to npm run, the script receives the wrong arguments.

CauseThe -- separator is missing, so npm parses the arguments itself.

FixWrite it as npm run dev -- --port 8080.

SymptomA globally installed package is still command not found inside the project.

CauseThe npm global bin directory is not in PATH.

FixRun npm bin -g to see the path and add it to PATH; better yet, use npx to avoid global installs.

SymptomThe npm cache directory keeps growing and builds get slower.

CauseThe cache has not been cleaned for a long time.

FixRun npm cache verify to check and clean it; in CI you can use --prefer-offline to reuse the cache and speed things up.

Troubleshooting

1Clean install from the lock file in CI
npm ci
Installs strictly from package-lock.json and deletes node_modules first—more reliable and faster than install.
2Confirm whether a package is installed and its version
npm ls <pkg>
Multiple versions in the output mean the dependency tree has a conflict.
3Trace which package pulled in a dependency
npm why <pkg>
Decides whether the dependency can be removed or needs to be declared explicitly in package.json.
4Troubleshoot version conflicts
npm ls --depth=0
Looking only at top-level direct dependencies is faster to scan by eye; once that checks out, look at the full tree.
5Run a package temporarily without a global install
npx create-react-app my-app
Avoids polluting the global environment; npx is also commonly used in CI for one-off tasks.

Command Examples

Trace which package pulled in a dependency

npm why lodash
npm ls lodash --depth=0

npm why traces backward, while npm ls shows the actually installed version tree. To troubleshoot version conflicts, start with npm ls to locate duplicate installs, then npm why to decide whether it can be removed.

Output

user@1.0.0 /home/tom/app
└── lodash@4.17.21

└── lodash@4.17.21

Use ci in CI for reproducibility

npm ci
# error example: ci fails immediately when package.json and the lock are out of sync

ci installs strictly from the lock and does not update versions, unlike install. When the lock and package.json are out of sync it fails immediately—exactly what you want: it surfaces a forgotten lock commit.

Output

npm warn old lockfile
npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync

Pin an exact version

npm install <pkg> --save-exact
# package.json will record "pkg": "1.2.3" instead of "^1.2.3"

-E/--save-exact removes the ^ prefix. Core dependencies are best pinned to an exact version, while secondary dependencies can use ^ to balance safe updates with reproducibility.

Common Pitfalls

package-lock.json belongs in Git; without it CI may resolve different versions and builds stop being reproducible.
npm install updates the lockfile and may upgrade dependencies — use npm ci in CI to install strictly from the lock.
^ permits minor upgrades while ~ permits only patches; pin core dependencies with --save-exact.
npx downloads and executes a remote package on the fly, which is running an unfamiliar script — verify the package first.
A globally installed CLI may differ in version from the project one; in CI prefer npx or npm run to use the local version.

Tips

npm install with no args installs all deps from package.json.
Commit package-lock.json to lock dependency versions.
npx runs a package without a global install, e.g. npx create-react-app my-app.
npm ci is faster and more reliable than npm install; needs a lockfile.
Set registry.npmmirror.com for a faster mirror in China.
audit fix --force may introduce breaking changes; be careful in production.

FAQ

What is the difference between npm ls and npm why?

npm ls prints the whole dependency tree, while npm ls --depth=0 shows only top-level dependencies and is far easier to scan. npm why <pkg> traces backwards to see which package pulled it in, which tells you what removing a dependency would break. Start with npm ls for version conflicts and npm why to explain why a package is present.

Should package-lock.json be committed to Git?

Yes. It pins the exact version of the entire dependency tree and is the precondition for reproducible builds. Once committed, CI should use npm ci rather than npm install: ci installs strictly from the lock file without updating versions and fails when the lock and package.json disagree, which surfaces the case where someone forgot to refresh the lock.

What do ^ and ~ mean in version ranges?

^ allows minor and patch upgrades but not a major bump: ^1.2.3 accepts any 1.x.x but not 2.0.0. ~ allows only patch upgrades: ~1.2.3 accepts 1.2.x but not 1.3.0. npm install --save-exact writes a prefix-free exact version, which suits libraries that need strict pinning.

How do I check dependencies for security vulnerabilities?

npm audit scans the tree and reports known issues, and npm audit fix upgrades to patched versions where possible. Use npm why <pkg> to trace what pulled a package in; if it arrives transitively, pin it via overrides in your direct dependencies or consider a lighter alternative. After any fix, rerun the test suite to confirm nothing broke.

When is npx preferable to a global install?

When the tool is needed only occasionally. npx <command> runs a local or remote package without installing it globally, so you skip the install/uninstall cycle and keep the global namespace clean. One-off scripts, ad-hoc debugging tools, and verifying a package CLI in CI all suit npx. For something you call constantly where startup time matters, a global install is still worth it.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Node.js Docs

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.