Why UNMET PEER DEPENDENCY Errors Appear and How to Fix Them in npm

The author encountered an UNMET PEER DEPENDENCY error while using npm list and, in investigating the cause, gained deeper insight into npm's package management mechanism.

What is UNMET PEER DEPENDENCY?

When running npm list, you may see an error like the one shown below:

Each line of the dependency tree that has a problem is accompanied by a line like this:

UNMET PEER DEPENDENCY means that a required peer version is missing. In the example, [email protected] requires an eslint version in the range 4.9.0 – 5.0.0, which is not installed.

Often a package inherits rules from another (e.g., Airbnb), so the required eslint version is missing from the tree, causing the warning at multiple levels.

Even after npm install, multiple versions of the same dependency can exist at different nodes of the tree. Understanding version number rules and npm's install behavior is essential.

Dependency Version Management Rules

When publishing an npm package, developers specify version constraints in package.json:

"dependencies": {
  "signale": "1.4.0",
  "figlet": "*",
  "react": "16.x",
  "table": "~5.4.6",
  "yargs": "^14.0.0"
}

These constraints follow the SemVer (Semantic Versioning) specification, originally drafted by GitHub.

SemVer official site: https://semver.org/

Examples of version specifiers:

"signale": "1.4.0"   // exact version
"figlet": "*"         // any version (>=0.0.0)
"react": "16.x"      // major version 16
"react": "16.3.x"    // major 16, minor 3

The ~ and ^ operators provide flexible ranges: ~: updates the patch version while keeping major and minor fixed. ^: updates both minor and patch versions while keeping the major version fixed.

When the major version is 0, both operators behave like a fixed version for the 0.0.x case, and only update the patch for 0.y.x.

To work with SemVer programmatically, install the semver package: npm install semver Common usages:

semver.valid('1.2.3')      // '1.2.3'
semver.valid('a.b.c')      // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.minVersion('>=1.0.0') // '1.0.0'

How npm install Constructs the Indirect Dependency Tree

After understanding version rules, consider a package A that depends on lodash@^2.2.0:

# node_modules/A/package.json
"dependencies": {
  "lodash": "^2.2.0"
}

If a project depends on A:

# project/package.json
"dependencies": {
  "A": "^1.0.0"
}

The resulting tree after npm install is:

`-- [email protected]
  `-- [email protected]

Adding another package B that requires a newer lodash version ( ^4.17.20) yields:

# project/package.json
"dependencies": {
  "B": "^4.3.2",
  "A": "^1.0.0"
}

After reinstalling, npm (v3+) flattens the tree:

+-- [email protected]
+-- [email protected]
`-- [email protected]
  `-- [email protected]

npm lifts the highest‑compatible version to the top level to avoid duplication.

The Root Cause: peerDependencies

npm defines several dependency fields in package.json:

dependencies

devDependencies

optionalDependencies

peerDependencies

bundledDependencies

UNMET PEER DEPENDENCY warnings arise from the peerDependencies field, which specifies the host package versions a plugin expects.

Example from [email protected] : <code>"peerDependencies": { "react": ">=16.9.0", "react-dom": ">=16.9.0" } </code> In npm 2, peer dependencies were installed automatically; in npm 3+ they are only warned about, requiring manual addition.

How to Resolve UNMET PEER DEPENDENCY

Manually installing the missing peer version (e.g., npm install lodash@^2.2.0) can downgrade the globally used version, potentially breaking other packages that rely on a newer version.

Best practice is to ask the package maintainer to update its peerDependencies. If you must suppress the warning, you can:

Globally install the missing peer without specifying a version (install all reported peers globally).

Enter each problematic node_modules subdirectory and install the required version manually (tedious).

Conclusion

The purpose of this article is not merely to fix UNMET PEER DEPENDENCY errors, but to use the phenomenon as a lens to understand npm's dependency management, version constraints, flattened node_modules structure, and lock‑file behavior.

References

Analysis of npm package management mechanisms

Overlooked details in npm dependency management