How to list/debug npm packages?

This article is based on Node v18.13.0

Installing and uninstalling dependencies are a core part of working with any Node.js project or framework React, Angular, NextJS, Express, Vue, etc. But how do you list your installed dependencies? If you are just starting with Node.js, have a look at the NodeJS intro article install node packages.

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

If you work on different projects with different environments and different node versions, surely, some effort is needed to manage this, and version conflicts are anything but nice. For example, globally installed dependencies, can cause version issues in your project, if you use a wrong version. Or you are currently in the process of a major update in a project, and try to upgrade the dependencies, and all of a sudden you get an error when installing. Most likely, npm ERR! Invalid version in the log after running npm install. Then you have to start to debug and the fun starts.

How to fix version conflicts in installed NPM Packages?

The first step when facing version issues with installed packages is to delete and reinstall.

1. Clean the node_modules folder rm -r node_modules
2. Re-install packages with npm install

If the issue still persists clean NPM cache. You can forcefully clean the NPM cache with npm cache clean --force

In a lot of cases, the issue is resolved now. If it isn't, you have to start debugging. First you have to list your installed packages

How to list installed NPM Packages?

The first step is the NPM, you are going to look for the npm ls command.

The npm ls [[<@scope>/]<pkg> ...] 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.

Let's create a small project and see what it prints out to stdout. Create a project with npm init and install a single dependency express.

mkdir npm-ls-test
cd npm-ls-test
npm init -y
npm i express

If you then run npm ls in the sample project folder, you will get the entire packages installed, when you install express.

[email protected]
└─┬ [email protected]
  ├─┬ [email protected]
  │ ├─┬ [email protected]
  │ │ └── [email protected]
  │ └── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected]
  │ ├── [email protected] deduped
  │ ├─┬ [email protected]
  │ │ └── [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├─┬ [email protected]
  │ │ ├── [email protected] deduped
  │ │ ├── [email protected] deduped
  │ │ ├── [email protected] deduped
  │ │ └── [email protected] deduped
  │ ├── [email protected] deduped
  │ └── [email protected]
  ├─┬ [email protected]
  │ └── [email protected] deduped
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ └── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ └── [email protected] deduped
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ └── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ └── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected]
  │ └── [email protected]
  ├─┬ [email protected]
  │ └─┬ [email protected]
  │   ├─┬ [email protected]
  │   │ ├── [email protected]
  │   │ └── [email protected] deduped
  │   ├─┬ [email protected]
  │   │ ├── [email protected] deduped
  │   │ ├─┬ [email protected]
  │   │ │ └── [email protected] deduped
  │   │ ├── [email protected]
  │   │ └── [email protected]
  │   └── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected]
  │ ├── [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ └── [email protected] deduped
  ├─┬ [email protected]
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ ├── [email protected] deduped
  │ └── [email protected] deduped
  ├── [email protected]
  ├── [email protected]
  ├─┬ [email protected]
  │ ├── [email protected]
  │ └── [email protected] deduped
  ├── [email protected]
  └── [email protected]

Without an argument npm ls lists all the dependencies down the dependency tree. If you are just interested in for example serve-static, you have to add an argument in the format name@version-range. Hence, you would do npm ls [email protected]. The stdout will be only for this package.

[email protected]
└─┬ [email protected]
  └── [email protected]

If you want to specify the depth in the dependency tree, add an argument for depth. The default level is infinity, which makes the stdout quite long. The stdout for npm-ls-test npm ls --depth=1, is only one level deep.

[email protected]
└─┬ [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  ├── [email protected]
  └── [email protected]

If you have found the culprit package, which causes the version conflict, and re-installing and cleaning the cache didn't resolve it, you can use the overrides section in the package.json to make changes to a specific package, see NPM.

For example, we want to use a specific version for super-nice-package, we can simply add the following code to the package.json.

{
  "overrides": {
    "super-nice-package": "12.15.1"
  }
}

Version conflicts can also arise when for example a maintainer of a package is lacking a bit behind another major package. Usually, after some time, the maintainer updates it, and the version conflicts get resolved, but until this happens, you can use the overrides method.

Be aware, to regularly update your project, and remove the overrides, if possible.

How to list installed globally packages?

You can list globally installed packages with npm ls --global or npm ls -g.

For example, if you use nvm, the output should look something like this. In this example I used npm ls -g --depth=0 to list my global installed packages.

/PATH/.nvm/versions/node/v18.13.0/lib
├── @angular/[email protected]
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]

Please be aware, that if you have to change a globally installed package for whatever reason (update cycle, security fixes, license updates, etc.) within a team of multiple developers, you have to communicate this to every relevant person.

TL;DR

• The NPM CLI has a built-in command to list dependencies npm ls.
• You can use the overrides section in the package.json to override specific dependencies.
• When facing version conflicts, remove and reinstall dependencies, and/or forcefully clean the npm cache to fix it.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

NodeJS, NPM, Kentaro