1---
2title: npm-query
3section: 1
4description: Dependency selector query
5---
6
7### Synopsis
8
9```bash
10npm query <selector>
11```
12
13### Description
14
15The `npm query` command allows for usage of css selectors in order to retrieve
16an array of dependency objects.
17
18### Piping npm query to other commands
19
20```bash
21# find all dependencies with postinstall scripts & uninstall them
22npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
23
24# find all git dependencies & explain who requires them
25npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
26```
27
28### Extended Use Cases & Queries
29
30```stylus
31// all deps
32*
33
34// all direct deps
35:root > *
36
37// direct production deps
38:root > .prod
39
40// direct development deps
41:root > .dev
42
43// any peer dep of a direct deps
44:root > * > .peer
45
46// any workspace dep
47.workspace
48
49// all workspaces that depend on another workspace
50.workspace > .workspace
51
52// all workspaces that have peer deps
53.workspace:has(.peer)
54
55// any dep named "lodash"
56// equivalent to [name="lodash"]
57#lodash
58
59// any deps named "lodash" & within semver range ^"1.2.3"
60#lodash@^1.2.3
61// equivalent to...
62[name="lodash"]:semver(^1.2.3)
63
64// get the hoisted node for a given semver range
65#lodash@^1.2.3:not(:deduped)
66
67// querying deps with a specific version
68#lodash@2.1.5
69// equivalent to...
70[name="lodash"][version="2.1.5"]
71
72// has any deps
73:has(*)
74
75// deps with no other deps (ie. "leaf" nodes)
76:empty
77
78// manually querying git dependencies
79[repository^=github:],
80[repository^=git:],
81[repository^=https://github.com],
82[repository^=http://github.com],
83[repository^=https://github.com],
84[repository^=+git:...]
85
86// querying for all git dependencies
87:type(git)
88
89// get production dependencies that aren't also dev deps
90.prod:not(.dev)
91
92// get dependencies with specific licenses
93[license=MIT], [license=ISC]
94
95// find all packages that have @ruyadorno as a contributor
96:attr(contributors, [email=ruyadorno@github.com])
97```
98
99### Example Response Output
100
101- 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
102
103```json
104[
105  {
106    "name": "",
107    "version": "",
108    "description": "",
109    "homepage": "",
110    "bugs": {},
111    "author": {},
112    "license": {},
113    "funding": {},
114    "files": [],
115    "main": "",
116    "browser": "",
117    "bin": {},
118    "man": [],
119    "directories": {},
120    "repository": {},
121    "scripts": {},
122    "config": {},
123    "dependencies": {},
124    "devDependencies": {},
125    "optionalDependencies": {},
126    "bundledDependencies": {},
127    "peerDependencies": {},
128    "peerDependenciesMeta": {},
129    "engines": {},
130    "os": [],
131    "cpu": [],
132    "workspaces": {},
133    "keywords": [],
134    ...
135  },
136  ...
137```
138
139### Expecting a certain number of results
140
141One common use of `npm query` is to make sure there is only one version of
142a certain dependency in your tree.  This is especially common for
143ecosystems like that rely on `typescript` where having state split
144across two different but identically-named packages causes bugs.  You
145can use the `--expect-results` or `--expect-result-count` in your setup
146to ensure that npm will exit with an exit code if your tree doesn't look
147like you want it to.
148
149
150```sh
151$ npm query '#react' --expect-result-count=1
152```
153
154Perhaps you want to quickly check if there are any production
155dependencies that could be updated:
156
157```sh
158$ npm query ':root>:outdated(in-range).prod' --no-expect-results
159```
160
161### Package lock only mode
162
163If 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).
164
165### Configuration
166
167#### `global`
168
169* Default: false
170* Type: Boolean
171
172Operates in "global" mode, so that packages are installed into the `prefix`
173folder instead of the current working directory. See
174[folders](/configuring-npm/folders) for more on the differences in behavior.
175
176* packages are installed into the `{prefix}/lib/node_modules` folder, instead
177  of the current working directory.
178* bin files are linked to `{prefix}/bin`
179* man pages are linked to `{prefix}/share/man`
180
181
182
183#### `workspace`
184
185* Default:
186* Type: String (can be set multiple times)
187
188Enable running a command in the context of the configured workspaces of the
189current project while filtering by running only the workspaces defined by
190this configuration option.
191
192Valid values for the `workspace` config are either:
193
194* Workspace names
195* Path to a workspace directory
196* Path to a parent workspace directory (will result in selecting all
197  workspaces within that folder)
198
199When set for the `npm init` command, this may be set to the folder of a
200workspace which does not yet exist, to create the folder and set it up as a
201brand new workspace within the project.
202
203This value is not exported to the environment for child processes.
204
205#### `workspaces`
206
207* Default: null
208* Type: null or Boolean
209
210Set to true to run the command in the context of **all** configured
211workspaces.
212
213Explicitly setting this to false will cause commands like `install` to
214ignore workspaces altogether. When not set explicitly:
215
216- Commands that operate on the `node_modules` tree (install, update, etc.)
217will link workspaces into the `node_modules` folder. - Commands that do
218other things (test, exec, publish, etc.) will operate on the root project,
219_unless_ one or more workspaces are specified in the `workspace` config.
220
221This value is not exported to the environment for child processes.
222
223#### `include-workspace-root`
224
225* Default: false
226* Type: Boolean
227
228Include the workspace root when workspaces are enabled for a command.
229
230When false, specifying individual workspaces via the `workspace` config, or
231all workspaces via the `workspaces` flag, will cause npm to operate only on
232the specified workspaces, and not on the root project.
233
234This value is not exported to the environment for child processes.
235
236#### `package-lock-only`
237
238* Default: false
239* Type: Boolean
240
241If set to true, the current operation will only use the `package-lock.json`,
242ignoring `node_modules`.
243
244For `update` this means only the `package-lock.json` will be updated,
245instead of checking `node_modules` and downloading dependencies.
246
247For `list` this means the output will be based on the tree described by the
248`package-lock.json`, rather than the contents of `node_modules`.
249
250
251
252#### `expect-results`
253
254* Default: null
255* Type: null or Boolean
256
257Tells npm whether or not to expect results from the command. Can be either
258true (expect some results) or false (expect no results).
259
260This config can not be used with: `expect-result-count`
261
262#### `expect-result-count`
263
264* Default: null
265* Type: null or Number
266
267Tells to expect a specific number of results from the command.
268
269This config can not be used with: `expect-results`
270## See Also
271
272* [dependency selectors](/using-npm/dependency-selectors)
273