[Solved] What does npm install –legacy-peer-deps do exactly? When is it recommended / What’s a potential use case?

Just ran into this error:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: [email protected]0.1.0
npm ERR! Found: [email protected]17.0.1
npm ERR! node_modules/react
npm ERR!   [email protected]"17.0.1" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer [email protected]"^16.8.0" from [email protected]2.0.4
npm ERR! node_modules/react-hook-mousetrap
npm ERR!   [email protected]"*" from the root project
npm ERR! 

The module I am trying to install seems to have a different peer dependency from what I have installed. It seems like npm changed its behaviour in this regard and now lets the install fail.

What can I do now to fix this? I don’t want to downgrade my React version for this.

I know there is a flag called --legacy-peer-deps but I am not sure what exactly this does and whether it’s recommended to use it / what the potential disadvantages are? I assume there is a reason npm did let the install fail.

It’s just strange because I was using yarn up until very recently and everything was fine.

Solution #1:

–legacy-peer-deps restores peerDependency installation behavior from NPM v4 thru v6

One way of thinking of this flag is that it isn’t doing something new; rather it’s telling NPM not to do something new, since NPM v7 now installs peerDependencies by default.

In many cases, this is leading to version conflicts, which will break the installation process.

The --legacy-peer-deps flag was introduced with v7 as a way to bypass peerDependency auto-installation; it tells NPM to ignore peer deps and proceed with the installation anyway. This is how things used to be with NPM v4 thru v6.

If you’re unclear about the difference between regular deps and peer deps, here is a bit of context:

Dependencies vs peerDependencies

Dependencies: Libraries or modules that an NPM module needs in order to work in production. (Example: I recently built a pie chart mocking library that uses Chance.js to calculate random numbers within a specified range; Chance is therefore a dependency of my module.)

peerDependencies: A peer dependency is a specific version or set of versions of a third-party software library that a module is designed to work with. They’re similar in concept to the relationship between a browser extension and a browser. (Example: react-redux has two quite logical peerDependencies: react and redux.)

This issue is being driven, in part, by React v17

Due to the overwhelming number of modules that haven’t specifically added React v17 as a peerDependency, it’s now commonplace to encounter the unable to resolve dependency tree error when running npm installs within a v17 React application.

This error will fire whenever a module (or any of its own dependencies) lists a previous version of React as a peerDependency without specifically including React v17 as well.

(Note: Similar behavior will occur with the major-version update of any other framework or library.)

How to check peerDependencies for any given module

NPM itself doesn’t list peer deps on the pages of a given module. However, there is a simple workaround to check for peer deps, either before or after install. Simply run:

npm info name-of-module peerDependencies

This command will return the name of each peerDependency along with all compatible version(s).


  • NPM v7 now installs peerDependencies by default; this was not the case with v4-v6
  • A peerDependency is a module that a given module is designed to work with
  • NPM modules must name specific versions of their peer dependencies
  • If you’re running, for example, a React v17 app and a module hasn’t listed React 17 as a peerDependency — but has listed older versions — it will blow up the installation
  • Adding --legacy-peer-deps to your npm installation will bypass peerDependency auto-installation, but this may result in conflicts due to potentially breaking changes
Respondent: Chris Perry

Solution #2:

Here’s how I solved this problem:

First, what’s happening: react-hook-mousetrap is looking for [email protected], but it is not finding it. Instead it is finding @react17.0.1, which is a newer version. For some reason mousetrap doesn’t like this newer version, and you are being notified (it is not a big deal, but they decided it was worth stopping your build).

One solution: forcibly install the specific version of react that mousetrap wants:

yarn install [email protected]16.8.0

What this does is roll back your react version to a slightly older one that is compatible with mousetrap. You won’t notice any difference, and in future iterations, hopefully mousetrap is updated, so this goes away.

Another solution: make a sweeping decision to install all older version dependencies:

npm install xxxx --legacy-peer-deps

What this does is roll back all dependencies to a version that this package prefers. It is more comprehensive, and makes the decisions for you (ie: it will do the command above, plus any others it finds).

Respondent: Israel Peck

The answers/resolutions are collected from stackoverflow, are licensed under cc by-sa 2.5 , cc by-sa 3.0 and cc by-sa 4.0 .

Most Popular

To Top
India and Pakistan’s steroid-soaked rhetoric over Kashmir will come back to haunt them both clenbuterol australia bossier man pleads guilty for leadership role in anabolic steriod distribution conspiracy