This error occurs when a package requires a peer dependency that is not installed in your project. Starting with npm 7, peer dependencies must be installed manually, and npm will fail the installation if they are missing.
This error indicates that a package you're trying to install or use has declared a peer dependency that is not present in your project's node_modules. Peer dependencies are packages that a library expects to be provided by the consuming application rather than bundling them directly. This is common with frameworks like React, where multiple packages need to share the same instance of the framework to work correctly. Starting with npm 7, peer dependencies are enforced strictly. If a peer dependency is missing or has an incompatible version, npm will fail the installation and show this error. This is different from npm 3-6, which only showed warnings.
Read the error message carefully to identify which peer dependency is missing and what version is required:
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from [email protected]
npm ERR! node_modules/some-packageThe error shows:
- Package name: react
- Required version: ^18.0.0
- Which package requires it: [email protected]
Install the peer dependency directly in your project:
npm install react@18Or if you need a specific version:
npm install [email protected]For development-only peer dependencies:
npm install --save-dev react@18After installation, run your original install command again.
The install-peerdeps utility automatically installs a package along with its peer dependencies:
npx install-peerdeps <package-name>For example:
npx install-peerdeps some-react-componentThis tool reads the package's peerDependencies and installs compatible versions automatically.
If you already have the peer dependency installed but with an incompatible version, check what's installed:
npm list reactCompare the installed version with the required version from the error. You may need to upgrade or downgrade:
# Upgrade to a compatible version
npm install react@latest
# Or install a specific compatible version
npm install [email protected]Check which packages depend on conflicting versions:
npm ls react --depth=0If you're still experiencing issues, try a clean installation:
# Remove node_modules and lock file
rm -rf node_modules package-lock.json
# Clear npm cache
npm cache clean --force
# Reinstall all dependencies
npm installThis ensures all dependencies are resolved fresh with current peer dependency requirements.
Using --legacy-peer-deps
You can bypass peer dependency checks using the --legacy-peer-deps flag:
npm install --legacy-peer-depsThis makes npm behave like versions 4-6, ignoring peer dependency conflicts. However, this is not recommended for production as it can lead to runtime errors when packages expect specific peer dependency versions.
Using --force
The --force flag is more aggressive and will override all conflicts:
npm install --forceThis should be used as a last resort, as it can result in broken or incompatible packages.
Setting in .npmrc
To always use legacy peer deps behavior, add to your .npmrc file:
legacy-peer-deps=trueUnderstanding peer dependency ranges
Peer dependencies use semantic versioning ranges:
- ^18.0.0 - Compatible with 18.0.0 and above (but below 19.0.0)
- >=18.0.0 <19.0.0 - Explicitly between versions
- * - Any version (not recommended)
Checking peer dependencies with tools
Use check-peer-dependencies to audit your project:
npx check-peer-dependenciesThis recursively finds all peer dependencies and checks if compatible versions are installed.
Yarn and pnpm behavior
Different package managers handle peer dependencies differently:
- Yarn 1: Issues warnings like npm 3-6
- Yarn 2+: Strictly enforces peer dependencies
- pnpm: Always installs peer dependencies but may require --shamefully-hoist flag for compatibility
Why peer dependencies exist
Peer dependencies solve the "singleton" problem. For frameworks like React, having multiple copies loaded simultaneously causes errors. By declaring React as a peer dependency, component libraries ensure they use the same React instance as your application.
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams