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