npm-query(1) npm-query(1)
NAME
npm-query - Dependency selector query
Synopsis
npm query <selector>
Description
The npm query command allows for usage of css selectors in order to
retrieve an array of dependency objects.
Piping npm query to other commands
# find all dependencies with postinstall scripts & uninstall them
npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
# find all git dependencies & explain who requires them
npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
Extended Use Cases & Queries
// all deps
*
// all direct deps
:root > *
// direct production deps
:root > .prod
// direct development deps
:root > .dev
// any peer dep of a direct deps
:root > * > .peer
// any workspace dep
// all workspaces that depend on another workspace
// all workspaces that have peer deps
// any dep named "lodash"
// equivalent to [name="lodash"]
#lodash
// any deps named "lodash" & within semver range ^"1.2.3"
#lodash@^1.2.3
// equivalent to...
[name="lodash"]:semver(^1.2.3)
// get the hoisted node for a given semver range
#lodash@^1.2.3:not(:deduped)
// querying deps with a specific version
#lodash@2.1.5
// equivalent to...
[name="lodash"][version="2.1.5"]
// has any deps
:has(*)
// deps with no other deps (ie. "leaf" nodes)
:empty
// manually querying git dependencies
[repository^=github:],
[repository^=git:],
[repository^=https://github.com],
[repository^=http://github.com],
[repository^=https://github.com],
[repository^=+git:...]
// querying for all git dependencies
:type(git)
// get production dependencies that aren't also dev deps
// get dependencies with specific licenses
[license=MIT], [license=ISC]
// find all packages that have @ruyadorno as a contributor
:attr(contributors, [email=ruyadorno@github.com])
Example Response Output
o an array of dependency objects is returned which can contain
multiple copies of the same package which may or may not have been
linked or deduped
[
{
"name": "",
"version": "",
"description": "",
"homepage": "",
"bugs": {},
"author": {},
"license": {},
"funding": {},
"files": [],
"main": "",
"browser": "",
"bin": {},
"man": [],
"directories": {},
"repository": {},
"scripts": {},
"config": {},
"dependencies": {},
"devDependencies": {},
"optionalDependencies": {},
"bundledDependencies": {},
"peerDependencies": {},
"peerDependenciesMeta": {},
"engines": {},
"os": [],
"cpu": [],
"workspaces": {},
"keywords": [],
...
},
...
Expecting a certain number of results
One common use of npm query is to make sure there is only one version
of a certain dependency in your tree. This is especially common for
ecosystems like that rely on typescript where having state split across
two different but identically-named packages causes bugs. You can use
the --expect-results or --expect-result-count in your setup to ensure
that npm will exit with an exit code if your tree doesn't look like you
want it to.
$ npm query '#react' --expect-result-count=1
Perhaps you want to quickly check if there are any production
dependencies that could be updated:
$ npm query ':root>:outdated(in-range).prod' --no-expect-results
Package lock only mode
If package-lock-only is enabled, only the information in the package
lock (or shrinkwrap) is loaded. This means that information from the
package.json files of your dependencies will not be included in the
result set (e.g. description, homepage, engines).
Configuration
global
o Default: false
o Type: Boolean
Operates in "global" mode, so that packages are installed into the
prefix folder instead of the current working directory. See npm help
folders for more on the differences in behavior.
o packages are installed into the {prefix}/lib/node_modules folder,
instead of the current working directory.
o bin files are linked to {prefix}/bin
o man pages are linked to {prefix}/share/man
workspace
o Default:
o Type: String (can be set multiple times)
Enable running a command in the context of the configured workspaces of
the current project while filtering by running only the workspaces
defined by this configuration option.
Valid values for the workspace config are either:
o Workspace names
o Path to a workspace directory
o Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
When set for the npm init command, this may be set to the folder of a
workspace which does not yet exist, to create the folder and set it up
as a brand new workspace within the project.
This value is not exported to the environment for child processes.
workspaces
o Default: null
o Type: null or Boolean
Set to true to run the command in the context of all configured
workspaces.
Explicitly setting this to false will cause commands like install to
ignore workspaces altogether. When not set explicitly:
o Commands that operate on the node_modules tree (install, update,
etc.) will link workspaces into the node_modules folder. - Commands
that do other things (test, exec, publish, etc.) will operate on
the root project, unless one or more workspaces are specified in
the workspace config.
This value is not exported to the environment for child processes.
include-workspace-root
o Default: false
o Type: Boolean
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the workspace config,
or all workspaces via the workspaces flag, will cause npm to operate
only on the specified workspaces, and not on the root project.
This value is not exported to the environment for child processes.
package-lock-only
o Default: false
o Type: Boolean
If set to true, the current operation will only use the package-
lock.json, ignoring node_modules.
For update this means only the package-lock.json will be updated,
instead of checking node_modules and downloading dependencies.
For list this means the output will be based on the tree described by
the package-lock.json, rather than the contents of node_modules.
expect-results
o Default: null
o Type: null or Boolean
Tells npm whether or not to expect results from the command. Can be
either true (expect some results) or false (expect no results).
This config cannot be used with: expect-result-count
expect-result-count
o Default: null
o Type: null or Number
Tells to expect a specific number of results from the command.
This config cannot be used with: expect-results
SEE ALSO
o npm help "dependency selectors"
NPM@11.6.2 October 2025 npm-query(1)
npm 11.6.2 - Generated Mon Oct 13 15:59:57 CDT 2025