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

NAME

6       npm-ls - List installed packages
7
8   Synopsis
9         npm ls <package-spec>
10
11         alias: list
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.19.2 /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 to 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   all
70       • Default: false
71
72       • Type: Boolean
73
74
75       When running npm outdated and npm ls, setting --all will show all  out‐
76       dated  or  installed packages, rather than only those directly depended
77       upon by the current project.
78
79   json
80       • Default: false
81
82       • Type: Boolean
83
84
85       Whether or not to output JSON data, rather than the normal output.
86
87       • In npm pkg set it enables parsing set values with JSON.parse() before
88         saving them to your package.json.
89
90
91       Not supported by all npm commands.
92
93   long
94       • Default: false
95
96       • Type: Boolean
97
98
99       Show extended information in ls, search, and help-search.
100
101   parseable
102       • Default: false
103
104       • Type: Boolean
105
106
107       Output  parseable  results from commands that write to standard output.
108       For npm search, this will be tab-separated table format.
109
110   global
111       • Default: false
112
113       • Type: Boolean
114
115
116       Operates in "global" mode, so that packages are installed into the pre‐
117       fix folder instead of the current working directory. See npm help fold‐
118       ers for more on the differences in behavior.
119
120       • packages are installed into the {prefix}/lib/node_modules folder, in‐
121         stead of the current working directory.
122
123       • bin files are linked to {prefix}/bin
124
125       • man pages are linked to {prefix}/share/man
126
127
128   depth
129       • Default: Infinity if --all is set, otherwise 1
130
131       • Type: null or Number
132
133
134       The depth to go when recursing packages for npm ls.
135
136       If  not  set,  npm  ls will show only the immediate dependencies of the
137       root project. If --all is set, then npm will show all  dependencies  by
138       default.
139
140   omit
141       • Default:  'dev'  if the NODE_ENV environment variable is set to 'pro‐
142         duction', otherwise empty.
143
144       • Type: "dev", "optional", or "peer" (can be set multiple times)
145
146
147       Dependency types to omit from the installation tree on disk.
148
149       Note that these dependencies are still resolved and added to the  pack‐
150       age-lock.json or npm-shrinkwrap.json file. They are just not physically
151       installed on disk.
152
153       If a package type appears in both the --include and --omit lists,  then
154       it will be included.
155
156       If  the  resulting omit list includes 'dev', then the NODE_ENV environ‐
157       ment variable will be set to 'production' for all lifecycle scripts.
158
159   link
160       • Default: false
161
162       • Type: Boolean
163
164
165       Used with npm ls, limiting output  to  only  those  packages  that  are
166       linked.
167
168   package-lock-only
169       • Default: false
170
171       • Type: Boolean
172
173
174       If  set  to  true,  the  current  operation  will  only  use  the pack‐
175       age-lock.json, ignoring node_modules.
176
177       For update this means only the package-lock.json will be  updated,  in‐
178       stead of checking node_modules and downloading dependencies.
179
180       For  list  this means the output will be based on the tree described by
181       the package-lock.json, rather than the contents of node_modules.
182
183   unicode
184       • Default: false on windows, true on mac/unix systems  with  a  unicode
185         locale, as defined by the LC_ALL, LC_CTYPE, or LANG environment vari‐
186         ables.
187
188       • Type: Boolean
189
190
191       When set to true, npm uses unicode characters in the tree output.  When
192       false, it uses ascii characters instead of unicode glyphs.
193
194   workspace
195       • Default:
196
197       • Type: String (can be set multiple times)
198
199
200       Enable running a command in the context of the configured workspaces of
201       the current project while filtering by running only the workspaces  de‐
202       fined by this configuration option.
203
204       Valid values for the workspace config are either:
205
206       • Workspace names
207
208       • Path to a workspace directory
209
210       • Path  to  a  parent workspace directory (will result in selecting all
211         workspaces within that folder)
212
213
214       When set for the npm init command, this may be set to the folder  of  a
215       workspace  which does not yet exist, to create the folder and set it up
216       as a brand new workspace within the project.
217
218       This value is not exported to the environment for child processes.
219
220   workspaces
221       • Default: null
222
223       • Type: null or Boolean
224
225
226       Set to true to run  the  command  in  the  context  of  all  configured
227       workspaces.
228
229       Explicitly  setting  this  to false will cause commands like install to
230       ignore workspaces altogether. When not set explicitly:
231
232       • Commands that operate on  the  node_modules  tree  (install,  update,
233         etc.)   will link workspaces into the node_modules folder. - Commands
234         that do other things (test, exec, publish, etc.) will operate on  the
235         root  project,  unless  one  or  more workspaces are specified in the
236         workspace config.
237
238
239       This value is not exported to the environment for child processes.
240
241   include-workspace-root
242       • Default: false
243
244       • Type: Boolean
245
246
247       Include the workspace root when workspaces are enabled for a command.
248
249       When false, specifying individual workspaces via the workspace  config,
250       or  all  workspaces  via the workspaces flag, will cause npm to operate
251       only on the specified workspaces, and not on the root project.
252
253       This value is not exported to the environment for child processes.
254
255   install-links
256       • Default: false
257
258       • Type: Boolean
259
260
261       When set file: protocol dependencies that exist outside of the  project
262       root  will  be  packed and installed as regular dependencies instead of
263       creating a symlink. This option has no effect on workspaces.
264
265   See Also
266       • npm help package spec
267
268       • npm help explain
269
270       • npm help config
271
272       • npm help npmrc
273
274       • npm help folders
275
276       • npm help explain
277
278       • npm help install
279
280       • npm help link
281
282       • npm help prune
283
284       • npm help outdated
285
286       • npm help update
287
288
289
290
291                                September 2022                       NPM-LS(1)