1NPM-LS(1) NPM-LS(1)
2
3
4
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.0.0 /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 to selecting all of
241 the nested workspaces)
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: false
255
256 • Type: Boolean
257
258
259 Enable running a command in the context of all the configured
260 workspaces.
261
262 This value is not exported to the environment for child processes.
263 <!-- automatically generated, do not edit manually --> <!-- see
264 lib/utils/config/definitions.js -->
265
266 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
267
268
269 See Also
270 • npm help explain
271
272 • npm help config
273
274 • npm help npmrc
275
276 • npm help folders
277
278 • npm help explain
279
280 • npm help install
281
282 • npm help link
283
284 • npm help prune
285
286 • npm help outdated
287
288 • npm help update
289
290
291
292
293 October 2021 NPM-LS(1)