How to fix Error: Peer dependency 'react' required but not installed in Node.js

Node.jsBEGINNERMEDIUMUpdated Dec 9, 2025· 131 views

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.

Quick fix

Fixes Error: Peer dependency 'react' required but not installed

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from some-package@1.0.0
npm ERR! node_modules/some-package
  1. Identify the missing peer dependency
  2. Install the missing peer dependency
  3. Use install-peerdeps for automatic installation
  4. Check for version conflicts
node.js — error
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from some-package@1.0.0
npm ERR! node_modules/some-package
Error: Peer dependency 'react' required but not installed

What this error means

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.

Typical symptoms

  • npm install command fails with peer dependency error
  • Package installation stops with "ERESOLVE unable to resolve dependency tree"
  • Error message lists specific peer dependency and required version range
  • Installation works with --legacy-peer-deps or --force flags
  • CI/CD pipeline fails during dependency installation
  • Fresh clone of repository fails to install dependencies

Common causes

  1. The peer dependency package is not installed in your project
  2. An incompatible version of the peer dependency is installed
  3. package-lock.json contains outdated or conflicting dependency resolutions
  4. Upgrading npm from version 6 to 7+ with existing projects
  5. Installing a package that requires a newer version of a peer dependency than your project uses
  6. Missing peer dependencies after deleting node_modules and reinstalling

How to fix "Error: Peer dependency 'react' required but not installed"

1Identify the missing peer dependency

Read the error message carefully to identify which peer dependency is missing and what version is required:

bash
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from some-package@1.0.0
npm ERR! node_modules/some-package

The error shows:
- Package name: react
- Required version: ^18.0.0
- Which package requires it: some-package@1.0.0

2Install the missing peer dependency

Install the peer dependency directly in your project:

bash
npm install react@18

Or if you need a specific version:

bash
npm install react@18.2.0

For development-only peer dependencies:

bash
npm install --save-dev react@18

After installation, run your original install command again.

3Use install-peerdeps for automatic installation

The install-peerdeps utility automatically installs a package along with its peer dependencies:

bash
npx install-peerdeps <package-name>

For example:

bash
npx install-peerdeps some-react-component

This tool reads the package's peerDependencies and installs compatible versions automatically.

4Check for version conflicts

If you already have the peer dependency installed but with an incompatible version, check what's installed:

bash
npm list react

Compare the installed version with the required version from the error. You may need to upgrade or downgrade:

bash
# Upgrade to a compatible version
npm install react@latest

# Or install a specific compatible version
npm install react@18.2.0

Check which packages depend on conflicting versions:

bash
npm ls react --depth=0
5Clean install if issues persist

If you're still experiencing issues, try a clean installation:

bash
# Remove node_modules and lock file
rm -rf node_modules package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall all dependencies
npm install

This ensures all dependencies are resolved fresh with current peer dependency requirements.

Advanced notes

Using --legacy-peer-deps

You can bypass peer dependency checks using the --legacy-peer-deps flag:

bash
npm install --legacy-peer-deps

This 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:

bash
npm install --force

This 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:

bash
legacy-peer-deps=true

Understanding 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:

bash
npx check-peer-dependencies

This 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.

Frequently asked questions

What does "Error: Peer dependency 'react' required but not installed" mean?
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.
How do I fix "Error: Peer dependency 'react' required but not installed"?
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.
What causes "Error: Peer dependency 'react' required but not installed"?
The peer dependency package is not installed in your project An incompatible version of the peer dependency is installed package-lock.json contains outdated or conflicting dependency resolutions
Is the "Error: Peer dependency 'react' required but not installed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading