npm-ls

Print all versions of direct dependencies in the current project to stdout

$ npm [[ls|list]]

$ npm [[ls|list]] [[-a|--all]]

$ npm [[ls|list]] [[-g|--global]]

$ npm [[ls|list]] [[-l|--long]]

$ npm [[ls|list]] [[-p|--parseable]]

$ npm [[ls|list]] --json

npm ls [<package-spec>] [<options>]

-g, --global
    List packages in the global install root instead of the current project.

--json
    Output results as a JSON object, useful for scripting and programmatic parsing.

--long
    Show extended information for each package, including licenses, description, and repository.

--parseable
    Output results in a format that is easily parseable by other commands or scripts, typically one package path per line.

--depth=
    Limit the depth of the dependency tree. --depth=0 shows only top-level dependencies.

--link
    Show only packages that are symlinked.

--production
    Display only production dependencies (excluding dev dependencies).

--development
    Display only development dependencies (excluding production dependencies).

--all
    Display all dependencies, including production, development, optional, peer, and bundled.

--omit
    Omit specific dependency types (e.g., dev, optional, peer). Can be specified multiple times.

--include
    Include specific dependency types (e.g., dev, optional, peer). Can be specified multiple times.

--dedupe
    Show a deduplicated tree. This is useful after running npm dedupe.

--versions
    Show only the package name and version number, without the full tree.

--silent
    Suppress all output, useful when only the exit code is needed.

--loglevel
    Set the logging level for the output (e.g., info, warn, error).

The npm ls command displays a tree of installed node_modules packages and their dependencies. By default, it lists packages installed locally in the current project directory. Using the -g or --global option, it can list packages installed globally across your system.

This command is invaluable for understanding the actual state of your project's dependencies, including their versions and the hierarchy in which they are installed. It helps in identifying potential issues like duplicate packages, hoisted dependencies, or unmet peer dependencies. The output can be an ASCII tree, which is easy to read, or a JSON object for programmatic parsing. It provides a quick overview of what's present in your node_modules folder, which may differ from what's declared in your package.json due to various installation processes or dependency conflicts.

For projects with a very large number of dependencies, the default ASCII tree output can be extremely verbose and slow to generate. Consider using --depth=0 or --json for better performance and readability.

The command displays what is actually installed in node_modules, which might not always align perfectly with the dependencies declared in your package.json due to hoisting, uninstalled packages, or differing versions from previous installations.

Output can contain warnings like UNMET PEER DEPENDENCY, indicating a peer dependency requirement that hasn't been met by a parent package. This isn't always an error but should be understood.

The `npm ls` command does not modify the filesystem; it is purely an inspection tool.

The default ASCII tree output indicates the hierarchical relationship between packages. Symbols like ` extraneous` or ` unmet peer dependency` provide critical information about the state of your installed packages. `extraneous` means the package is installed but not listed in package.json, while `unmet peer dependency` means a required peer dependency for a package is missing.

Understanding dependency types is crucial. Dependencies are required for the application to run. DevDependencies are only needed for development and testing. PeerDependencies are required by the package itself, but not installed directly by npm; the consuming project is expected to provide them. OptionalDependencies are optional and don't cause installation failure if missing. BundledDependencies are an array of package names that are bundled when publishing.

For very deep or wide dependency trees, `npm ls` can consume significant memory and time. Using options like --depth, --production, or piping the output to `grep` or `less` can significantly improve its usability and performance in large projects.

The npm ls command has been a fundamental utility within the npm CLI since its early days, evolving alongside npm's dependency resolution algorithms and the structure of the node_modules directory. Its core functionality of displaying the installed dependency tree has remained constant, but new options have been added over time to provide more granular control over output format, depth, and the types of dependencies to display, reflecting the growing complexity of modern JavaScript projects and the need for better introspection tools. It continues to be one of the most frequently used npm commands for developers to debug and understand their project's dependency graph.

npm install(1), npm uninstall(1), npm update(1), npm view(1), npm outdated(1), npm prune(1), npm help(1)