npm peer dependency conflict / ERESOLVE — how to fix

Quick Answer

# Show why the conflicting package is installed
npm explain some-library

# Check the peer dependency range required by that package
npm info some-library@latest peerDependencies

# Upgrade or select compatible versions, then install again
npm install some-library@latest
npm install

When this happens

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   react@"^18.3.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from [email protected]

A dependency requires a specific peer dependency version that conflicts with another installed version. This is the typical npm peer dependency conflict.

Other causes & fixes

Find the incompatible version requirement

Read both the package version npm found and the peer dependency range it could not satisfy. Then choose package versions whose ranges overlap.

npm explain some-library
npm info some-library versions --json
npm info [email protected] peerDependencies

Install compatible package versions

# Check if a newer version supports your peer dep version
npm info some-library peerDependencies

# Install a version with a compatible peer dependency range
npm install [email protected]

Bypass the check only as a temporary fallback

These flags do not make incompatible packages compatible. Run the project tests before keeping an installation created with either option.

# --legacy-peer-deps: ignores peer dep conflicts (npm 6 behavior)
# --force: allows npm to install despite conflicting protections
npm install --legacy-peer-deps
npm install --force