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