npm ERR! peer dep missing

A package requires another package to be installed alongside it.

Frequently documented in developer and vendor support forums.

• Peer dependency not in package.json
• Version mismatch with peer
• npm 7+ strict peer dependency checking

1. Install the missing peer dependency manually
2. Use --legacy-peer-deps flag
3. Update packages to compatible versions

Last reviewed: March 2026 How we review solutions

npm emits peer dependency warnings (npm 7+) or errors when a package declares a peerDependency that is not installed at the required version. Peer dependencies are a declaration by a package that it needs a specific library to be provided by the consuming project, rather than installing its own copy. This pattern is used by plugins, extensions, and frameworks: React component libraries declare react as a peer dependency because they need to use the same React instance as your application (having two copies of React causes subtle bugs with hooks and context). When you install a package with unmet peer dependencies, npm 7+ warns by default and npm 8+ can error depending on configuration. The most common cause is version mismatches: your project has React 17 but a component library requires React 18 as a peer. The second most common cause is missing top-level installations: you installed a plugin (e.g., eslint-plugin-react) but never installed its peer dependency (eslint) explicitly. npm 6 and earlier automatically installed peer dependencies, but npm 7+ changed this to require explicit installation, causing many existing projects to see these warnings for the first time after upgrading npm.

1. Read the warning to see which peer dependency is missing and what version is needed
2. Install the missing peer dependency: npm install peer-package@required-version
3. Check for version conflicts: npm ls peer-package
4. If peer versions conflict, check if the package supports your version
5. Use --legacy-peer-deps to install without resolving peers (temporary workaround)

Multiple packages requiring different peer versions

If package A needs react@^17 and package B needs react@^18, you cannot satisfy both. Check if package A has an updated version supporting React 18. If not, you may need to replace one of the packages with an alternative that supports your React version.

npm 6 to npm 7+ migration

npm 6 auto-installed peer dependencies. npm 7+ does not. When upgrading npm, existing projects suddenly show peer dependency warnings. Run npm install to let npm 7+ attempt to resolve peers, or add missing peers manually.

Monorepo with shared peer dependencies

In npm workspaces, peer dependencies should be installed in the root package.json so all workspace packages share the same instance. If a peer is installed in a workspace package instead of the root, other packages may not see it.

What is a peer dependency?

A package that must be installed by the consumer rather than automatically.

Why did this work before?

npm 7+ enforces peer dependencies more strictly than earlier versions.

What does --legacy-peer-deps do?

It tells npm to ignore peer dependency conflicts and install packages the way npm 6 did. This is a temporary workaround—packages may not work correctly if their peer requirements are unmet. Use it only when you cannot resolve the conflict through version changes.

Why do packages use peer dependencies instead of regular dependencies?

Peer dependencies ensure all code uses the same instance of a shared library. If a React component library bundled its own copy of React, your app would have two React instances, causing hooks, context, and state to break. Peer dependencies force a single shared copy.

How do I find which version of a peer dependency to install?

Check the package documentation or run npm view package-name peerDependencies. This shows the exact version ranges the package expects. Install a version that satisfies all peer requirements from all your dependencies.

• npm install – Official npm Docs
• package.json Reference – npm Docs