1NPM-LS(1)                                                            NPM-LS(1)
2
3
4

NAME

6       npm-ls - List installed packages
7
8   Synopsis
9         npm ls [[<@scope>/]<pkg> ...]
10
11         aliases: list, la, ll
12
13   Description
14       This command will print to stdout all the versions of packages that are
15       installed, as well as their dependencies when --all is specified, in  a
16       tree structure.
17
18       Note:  to get a "bottoms up" view of why a given package is included in
19       the tree at all, use npm help explain.
20
21       Positional arguments are  name@version-range  identifiers,  which  will
22       limit  the  results to only the paths to the packages named.  Note that
23       nested packages will also show the paths  to  the  specified  packages.
24       For example, running npm ls promzard in npm's source tree will show:
25
26         npm@8.3.1 /path/to/npm
27         └─┬ init-package-json@0.0.4
28           └── promzard@0.1.5
29
30       It will print out extraneous, missing, and invalid packages.
31
32       If  a  project  specifies  git urls for dependencies these are shown in
33       parentheses after the name@version to make it easier for users to  rec‐
34       ognize potential forks of a project.
35
36       The  tree shown is the logical dependency tree, based on package depen‐
37       dencies, not the physical layout of your node_modules folder.
38
39       When run as ll or la, it shows extended information by default.
40
41   Note: Design Changes Pending
42       The npm ls command's output and behavior made a ton of sense  when  npm
43       created a node_modules folder that naively nested every dependency.  In
44       such a case, the logical dependency graph and physical tree of packages
45       on disk would be roughly identical.
46
47       With the advent of automatic install-time deduplication of dependencies
48       in npm v3, the ls output was modified to display the logical dependency
49       graph  as  a  tree structure, since this was more useful to most users.
50       However, without using npm ls -l, it became  impossible  show  where  a
51       package was actually installed much of the time!
52
53       With  the  advent  of automatic installation of peerDependencies in npm
54       v7, this gets even more curious, as peerDependencies are logically "un‐
55       derneath"  their  dependents  in  the  dependency graph, but are always
56       physically at or above their location on disk.
57
58       Also, in the years since npm got an ls command (in version 0.0.2!), de‐
59       pendency  graphs have gotten much larger as a general rule.  Therefore,
60       in order to avoid dumping an excessive amount of content to the  termi‐
61       nal,  npm ls now only shows the top level dependencies, unless --all is
62       provided.
63
64       A thorough re-examination of the use cases,  intention,  behavior,  and
65       output  of  this  command,  is  currently underway.  Expect significant
66       changes to at least the default human-readable npm ls output in npm v8.
67
68   Configuration
69       <!-- AUTOGENERATED CONFIG DESCRIPTIONS  START  -->  <!--  automatically
70       generated,  do  not edit manually --> <!-- see lib/utils/config/defini‐
71       tions.js -->
72
73   all
74       • Default: false
75
76       • Type: Boolean
77
78
79       When running npm outdated and npm ls, setting --all will show all  out‐
80       dated  or  installed packages, rather than only those directly depended
81       upon by the current project.  <!-- automatically generated, do not edit
82       manually --> <!-- see lib/utils/config/definitions.js -->
83
84
85   json
86       • Default: false
87
88       • Type: Boolean
89
90
91       Whether or not to output JSON data, rather than the normal output.
92
93       • In npm pkg set it enables parsing set values with JSON.parse() before
94         saving them to your package.json.
95
96
97       Not supported by all npm commands.  <!--  automatically  generated,  do
98       not edit manually --> <!-- see lib/utils/config/definitions.js -->
99
100
101   long
102       • Default: false
103
104       • Type: Boolean
105
106
107       Show  extended  information in ls, search, and help-search.  <!-- auto‐
108       matically generated, do not edit manually --> <!--  see  lib/utils/con‐
109       fig/definitions.js -->
110
111
112   parseable
113       • Default: false
114
115       • Type: Boolean
116
117
118       Output  parseable  results from commands that write to standard output.
119       For npm search, this will be tab-separated table format.  <!-- automat‐
120       ically  generated,  do  not  edit  manually --> <!-- see lib/utils/con‐
121       fig/definitions.js -->
122
123
124   global
125       • Default: false
126
127       • Type: Boolean
128
129
130       Operates in "global" mode, so that packages are installed into the pre‐
131       fix folder instead of the current working directory. See npm help fold‐
132       ers for more on the differences in behavior.
133
134       • packages are installed into the {prefix}/lib/node_modules folder, in‐
135         stead of the current working directory.
136
137       • bin files are linked to {prefix}/bin
138
139       • man pages are linked to {prefix}/share/man
140
141       <!--  automatically  generated,  do  not  edit  manually  -->  <!-- see
142       lib/utils/config/definitions.js -->
143
144
145   depth
146       • Default: Infinity if --all is set, otherwise 1
147
148       • Type: null or Number
149
150
151       The depth to go when recursing packages for npm ls.
152
153       If not set, npm ls will show only the  immediate  dependencies  of  the
154       root  project.  If --all is set, then npm will show all dependencies by
155       default.  <!-- automatically generated, do not edit manually  -->  <!--
156       see lib/utils/config/definitions.js -->
157
158
159   omit
160       • Default:  'dev'  if the NODE_ENV environment variable is set to 'pro‐
161         duction', otherwise empty.
162
163       • Type: "dev", "optional", or "peer" (can be set multiple times)
164
165
166       Dependency types to omit from the installation tree on disk.
167
168       Note that these dependencies are still resolved and added to the  pack‐
169       age-lock.json or npm-shrinkwrap.json file. They are just not physically
170       installed on disk.
171
172       If a package type appears in both the --include and --omit lists,  then
173       it will be included.
174
175       If  the  resulting omit list includes 'dev', then the NODE_ENV environ‐
176       ment variable will be set to 'production' for  all  lifecycle  scripts.
177       <!--  automatically  generated,  do  not  edit  manually  -->  <!-- see
178       lib/utils/config/definitions.js -->
179
180
181   link
182       • Default: false
183
184       • Type: Boolean
185
186
187       Used with npm ls, limiting output  to  only  those  packages  that  are
188       linked.   <!--  automatically  generated, do not edit manually --> <!--
189       see lib/utils/config/definitions.js -->
190
191
192   package-lock-only
193       • Default: false
194
195       • Type: Boolean
196
197
198       If set  to  true,  the  current  operation  will  only  use  the  pack‐
199       age-lock.json, ignoring node_modules.
200
201       For  update  this means only the package-lock.json will be updated, in‐
202       stead of checking node_modules and downloading dependencies.
203
204       For list this means the output will be based on the tree  described  by
205       the  package-lock.json, rather than the contents of node_modules.  <!--
206       automatically  generated,  do  not   edit   manually   -->   <!--   see
207       lib/utils/config/definitions.js -->
208
209
210   unicode
211       • Default:  false  on  windows, true on mac/unix systems with a unicode
212         locale, as defined by the LC_ALL, LC_CTYPE, or LANG environment vari‐
213         ables.
214
215       • Type: Boolean
216
217
218       When  set to true, npm uses unicode characters in the tree output. When
219       false, it uses ascii characters instead of unicode glyphs.  <!--  auto‐
220       matically  generated,  do not edit manually --> <!-- see lib/utils/con‐
221       fig/definitions.js -->
222
223
224   workspace
225       • Default:
226
227       • Type: String (can be set multiple times)
228
229
230       Enable running a command in the context of the configured workspaces of
231       the  current project while filtering by running only the workspaces de‐
232       fined by this configuration option.
233
234       Valid values for the workspace config are either:
235
236       • Workspace names
237
238       • Path to a workspace directory
239
240       • Path to a parent workspace directory (will result  in  selecting  all
241         workspaces within that folder)
242
243
244       When  set  for the npm init command, this may be set to the folder of a
245       workspace which does not yet exist, to create the folder and set it  up
246       as a brand new workspace within the project.
247
248       This  value  is  not  exported  to the environment for child processes.
249       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
250       lib/utils/config/definitions.js -->
251
252
253   workspaces
254       • Default: null
255
256       • Type: null or Boolean
257
258
259       Set  to  true  to  run  the  command  in  the context of all configured
260       workspaces.
261
262       Explicitly setting this to false will cause commands  like  install  to
263       ignore workspaces altogether. When not set explicitly:
264
265       • Commands  that  operate  on  the  node_modules tree (install, update,
266         etc.)  will link workspaces into the node_modules folder. -  Commands
267         that  do other things (test, exec, publish, etc.) will operate on the
268         root project, unless one or more  workspaces  are  specified  in  the
269         workspace config.
270
271
272       This  value  is  not  exported  to the environment for child processes.
273       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
274       lib/utils/config/definitions.js -->
275
276
277   include-workspace-root
278       • Default: false
279
280       • Type: Boolean
281
282
283       Include the workspace root when workspaces are enabled for a command.
284
285       When  false, specifying individual workspaces via the workspace config,
286       or all workspaces via the workspaces flag, will cause  npm  to  operate
287       only  on  the  specified workspaces, and not on the root project.  <!--
288       automatically  generated,  do  not   edit   manually   -->   <!--   see
289       lib/utils/config/definitions.js -->
290
291       <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
292
293
294   See Also
295       • npm help explain
296
297       • npm help config
298
299       • npm help npmrc
300
301       • npm help folders
302
303       • npm help explain
304
305       • npm help install
306
307       • npm help link
308
309       • npm help prune
310
311       • npm help outdated
312
313       • npm help update
314
315
316
317
318                                 January 2022                        NPM-LS(1)
Impressum