Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

npm refuses to install a React library because of peerDependencies

ErrorThe package react@15.3.2 does not satisfy its siblings' peerDependencies requirements

Short answer

The library declares which React version it works with, and your project has a different one. npm normally warns and resolves it, but with strict-peer-deps on any conflict becomes a failure. Check that setting, then upgrade the library to a release that lists your React, and use legacy-peer-deps only as a last resort.

  • Applies to npm 10, Node.js 22, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the full npm output: it names the package that asks for a React version and the version you have. Also print the npm settings that change peer handling.

    npm ls react
    npm config get strict-peer-deps
    npm config get legacy-peer-deps
  2. 2Match what you see, then jump to its fix

    1. 1npm config get strict-peer-deps prints true, or .npmrc contains itstrict-peer-deps is turned onFix
    2. 2npm names the library and a React range that excludes your versionThe library supports a different React than your projectFix

What does the error look like?

  • The package react@15.3.2 does not satisfy its siblings' peerDependencies requirements

Cause 1 of 2

strict-peer-deps is turned on

1Check

With strict-peer-deps set, any conflicting peerDependencies are treated as an install failure instead of a warning.

cat .npmrc ~/.npmrc 2>/dev/null | grep -i peer

2Fix

Remove the setting, so npm warns about the conflict and resolves using the nearest non-peer dependency.

npm config delete strict-peer-deps
npm install

3Verify

Install again and check the library is in the tree.

npm ls react

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 2

The library supports a different React than your project

1Check

Compare your React version with the peerDependencies of the library version you are installing.

npm view @mui/material peerDependencies

2Fix

Install a release of the library whose peer range includes your React. If none exists yet, install while ignoring peer dependencies, knowing that npm then does not enforce the contract.

npm install @mui/material@latest
# last resort, ignores peerDependencies like npm 3 to 6 did
npm install @mui/material --legacy-peer-deps

3Verify

Start the app and use a component from the library.

npm ls react && npm start

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Upgrade React and its ecosystem libraries together, not one at a time.
  • Check a library's peerDependencies before adopting it.
  • Avoid --force; npm's docs say it removes protections against common mistakes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.