npm-list

View documentation for the original command

$ tldr npm ls

npm list [package_spec] [options]

Example: npm list
Example: npm list react --depth=0
Example: npm list --global --json

--depth=
    Limits the depth of the dependency tree. 0 shows only top-level packages.

--global / -g
    Lists packages installed globally rather than in the current project.

--json
    Outputs the dependency tree in JSON format, useful for programmatic parsing.

--parseable / -p
    Outputs a list of package paths, one per line, suitable for scripting.

--long / -l
    Shows more detailed information about each package, including licenses and repository URLs.

--prod / --production
    Lists only production dependencies (excludes development dependencies).

--dev / --development
    Lists only development dependencies (excludes production dependencies).

--link
    Displays only packages that are symlinked (e.g., via npm link).

--omit=
    Omits specific types of dependencies. type can be dev, optional, or peer. Can be used multiple times.

--include=
    Includes specific types of dependencies. type can be dev, optional, or peer. Can be used multiple times.

--package-lock-only
    Reads and lists dependencies only from the package-lock.json (or npm-shrinkwrap.json) file.

--workspaces
    Lists dependencies for all configured workspaces in the current project.

--include-workspace-root
    When used with --workspaces, includes the workspace root project's dependencies in the output.

--loglevel=
    Sets the level of logging output. Common levels: silent, error, warn, http, info, verbose, silly.

The npm list command (also aliased as npm ls) displays a tree of all installed packages in the current project, or globally if the --global flag is used. It shows dependencies, their versions, and their own dependencies, forming a hierarchical structure.

This command is crucial for understanding your project's dependency graph, identifying package versions, and troubleshooting dependency-related issues like conflicts or missing packages. By default, it lists top-level packages and their immediate dependencies. Options allow controlling the depth of the tree, output format (human-readable, JSON, parseable), and filtering by package type (production, development). It helps visualize the entire dependency ecosystem within a project.

Large projects with deep dependency trees can produce extremely long outputs, making it difficult to read in the terminal. Using options like --depth, --json, or --parseable is highly recommended for managing output.

The command might show UNMET PEER DEPENDENCY warnings if peer dependencies are not satisfied. These are warnings, not errors, and indicate that a package expects a certain version of another package that isn't met by your current installation.

If node_modules is corrupted or missing, the command might fail or show an incomplete tree. Running npm install beforehand can resolve this.

The default output of npm list is a graphical representation of the dependency tree, using ASCII characters to show parent-child relationships. Each line typically shows the package name, its version, and sometimes additional indicators like deduped or linked.

By default, npm list inspects the actual node_modules directory. However, when --package-lock-only is used, it reads the tree structure purely from the package-lock.json file, which reflects the exact dependency tree that npm install would create, without needing the node_modules directory to exist or be complete.

npm list shows symlinked packages (e.g., those installed via npm link) differently, often indicating them with an arrow (->) and their source path. The --link option allows filtering the output to only show these linked packages.

The npm list command has been a fundamental part of npm since its early versions, providing core functionality for inspecting the project's dependency graph. As npm evolved, new options were added to enhance its utility, such as --json for programmatic interaction, --depth for controlling output size, and support for workspaces. Its purpose remains consistent: to offer a clear, structured view of all installed Node.js packages and their relationships within a project or globally.

npm install(1), npm uninstall(1), npm outdated(1), npm view(1), npm ls(1), yarn why(1), pnpm list(1)