How do you use npm query to find risky dependencies?

npm query returns the dependencies in your tree that match a CSS-style selector, as JSON. You can ask for every git dependency, every package with a postinstall script, every copy of one package, or every production dependency that is not also a dev dependency, then pipe the result to other tools.

The shape of a query

The npm docs describe the command as dependency selector queries. A selector like :root > .prod means direct production dependencies, and #lodash means any dependency named lodash. Results come back as an array of dependency objects, and the array can hold several copies of the same package, because different parts of the tree may carry different versions.

Queries worth saving

Taken from the npm documentation:

# all git dependencies, then explain who requires them
npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}

# dependencies with a postinstall script
npm query ":attr(scripts, [postinstall])"

# direct production dependencies
npm query ":root > .prod"

# production dependencies that are not also dev dependencies
npm query ".prod:not(.dev)"

# any dependency with specific licenses
npm query "[license=MIT], [license=ISC]"

# exactly one copy of react
npm query "#react" --expect-result-count=1

The docs' own example for scripts pipes the names to npm uninstall. Do not copy that line blindly. Listing is safe. Removing is a decision for a human.

Using it in an incident

When an advisory names a package and a version range, you want to know quickly whether you have it, where, and who pulled it in. A selector does the first two:

npm query "#example-package@^1.2.3"

Then run npm why for each result to trace the path. Our post on npm explain walks through that second step.

Using it as a guardrail

The expect-result-count and expect-results options make npm exit with a failure when the tree does not match what you want. The docs show a single version of react as an example, and suggest that duplicated state across two copies of a library can cause bugs. The same mechanism can express other rules about the shape of your tree. Check npm help for the exact options on your installed version.

Lockfile-only mode

If package-lock-only is enabled, npm loads only the lockfile. Fields that come from each dependency's package.json, such as description, homepage and engines, will not be in the result. That is fine for names and versions, and it is faster because it does not need node_modules.

Limits

• The output is only as good as the tree npm builds. If your project uses another package manager, use that manager's own tooling.
• Query results show what is installed, not whether a vulnerability is reachable in your code.
• Packages bundled inside another package may need extra care, as covered in bundledDependencies and scanner blind spots.

Try it yourself

Click through it at your own pace, or open it full screen. Look at how an inventory lists direct and transitive components in one view.

Where Safeguard fits

npm query answers questions about one project on one machine. Safeguard's SBOM and dependency scanning build the same inventory across repositories from lockfiles, so you can ask which projects contain a package. A free scan is at https://gold.safeguard.sh/scan.

Quick check

Sources

• npm query documentation

Last reviewed: 19 October 2026.