How Do I Resolve npm and Yarn Dependency Conflicts?

TL;DR

• Bottom line: Most npm/yarn dependency conflicts are caused by incompatible peer dependency versions. The proper fix is to align versions via npm ls, npm explain, and targeted upgrades. Use overrides (npm) or resolutions (yarn) for transitive dependency pinning. --legacy-peer-deps and --force are escape hatches, not solutions.
• Key tool/command: npm explain <package> to trace the conflict chain, then either npm update the parent or add "overrides" to package.json.
• Watch out for: Using --force or --legacy-peer-deps globally — they hide real incompatibilities that surface as runtime errors. Never set legacy-peer-deps=true in global .npmrc.
• Works with: npm 7+ (ERESOLVE enforcement), npm 8.3+ (overrides), Yarn Classic v1 (resolutions), Yarn Berry v2+ (resolutions), pnpm 7+ (strict peer mode).

Constraints

• Never recommend --force or --legacy-peer-deps as a first solution — always diagnose the conflict first with npm ls and npm explain. [src6]
• overrides only works in the root package.json — nested/workspace overrides are ignored by npm. [src1, src5]
• Yarn resolutions must be in the root package.json for workspaces — inner package resolutions are ignored for hoisted dependencies. [src3]
• After any override/resolution change, delete node_modules and lockfile, then reinstall. Stale lockfiles are the #1 cause of "override not working" reports. [src5]
• pnpm does NOT auto-install conflicting peer dependencies — it prints a warning and skips them. You must manually choose a version. [src4]
• npm overrides requires npm >= 8.3.0 — older versions silently ignore the overrides field. [src2, src5]

Quick Reference

Decision Tree

START — npm/yarn install fails with dependency conflict
├── Which package manager?
│   ├── npm 7+
│   │   ├── Error says "ERESOLVE unable to resolve dependency tree"?
│   │   │   ├── YES → Run `npm explain <conflicting-package>` [src6]
│   │   │   │   ├── Can you upgrade the parent package?
│   │   │   │   │   ├── YES → `npm install <parent>@latest`
│   │   │   │   │   └── NO → Add `overrides` to package.json [src1, src5]
│   │   │   │   └── Is this a dev-only tool (linter, test runner)?
│   │   │   │       ├── YES → `--legacy-peer-deps` is acceptable [src6]
│   │   │   │       └── NO → Fix with overrides
│   │   │   └── NO → Check `npm ls` for version conflicts
│   │   └── Error says "peer dep ... from ..."?
│   │       └── `npm explain <package>` → upgrade or override [src7]
│   ├── Yarn Classic (v1) or Yarn Berry (v2+)
│   │   └── Add `resolutions` to root package.json → `yarn install` [src3]
│   └── pnpm
│       └── Install missing peer or configure peerDependencyRules [src4]
└── Still failing?
    └── Nuclear: rm -rf node_modules package-lock.json && npm cache clean --force && npm install [src6]

Step-by-Step Guide

1. Identify the conflicting packages

Run npm install and read the ERESOLVE output carefully. It tells you exactly which packages conflict. [src6]

# See the full error (npm truncates by default)
npm install 2>&1 | head -80

# Or use verbose mode for maximum detail
npm install --verbose 2>&1 | grep -A 5 "ERESOLVE"

Verify: The error shows While resolving: [email protected] and Could not resolve dependency: peer react@"^17.0.0" from [email protected].

2. Understand why each version is required

Use npm explain (alias: npm why) to trace the dependency chain. [src5, src6]

# Show which packages depend on react and what versions they require
npm explain react

# Tree view of all installed versions
npm ls react

# Check for all outdated packages
npm outdated

Verify: npm explain react shows each dependant with its required version range.

3. Attempt version alignment (preferred fix)

Update the package that has the outdated peer dependency requirement. [src7]

# Update a specific package to its latest version
npm install @testing-library/react@latest

# Update all packages to latest compatible versions
npm update

# Check what would change without modifying anything
npm update --dry-run

Verify: npm ls react shows a single version with no UNMET PEER DEPENDENCY warnings.

4. Use overrides for npm (when alignment is impossible)

When a transitive dependency pins an incompatible version and no update is available. [src1, src5]

{
  "dependencies": {
    "some-library": "^2.0.0"
  },
  "overrides": {
    "react": "^18.2.0",
    "some-library": {
      "old-subdep": "2.0.0"
    }
  }
}

# After adding overrides, always clean install
rm -rf node_modules package-lock.json
npm install

# Verify the override took effect
npm ls old-subdep
npm explain old-subdep

Verify: npm ls old-subdep shows only the overridden version.

5. Use resolutions for Yarn

Yarn Classic and Berry both support resolutions in package.json. [src3]

{
  "dependencies": {
    "some-library": "^2.0.0"
  },
  "resolutions": {
    "react": "18.2.0",
    "**/lodash": "4.17.21",
    "some-library/old-subdep": "2.0.0"
  }
}

# Clean install after changing resolutions
rm -rf node_modules yarn.lock
yarn install

# Verify
yarn why react

6. Configure pnpm peer dependency rules

pnpm provides granular control via pnpm.peerDependencyRules in package.json. [src4]

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/core"],
      "allowedVersions": {
        "react": "18"
      },
      "allowAny": ["eslint"]
    },
    "overrides": {
      "lodash": "4.17.21"
    }
  }
}

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Verify
pnpm why react

Code Examples

package.json: npm overrides for React peer conflict

// Input:  Library requires react@^17 but project uses react@18
// Output: Forces all packages to accept [email protected]

{
  "name": "my-app",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "legacy-component-lib": "^3.0.0"
  },
  "overrides": {
    "react": "$react",
    "react-dom": "$react-dom"
  }
}
// Note: "$react" references the version in your own dependencies.
// Requires npm >= 8.3.0. [src1, src2]

.npmrc: project-level configuration for persistent flags

# Input:  Project that must use --legacy-peer-deps on every install
# Output: Flag applied automatically without passing it each time

# .npmrc (place in project root, commit to git)
legacy-peer-deps=true

# Prefer deduplication when resolving (npm 8.13+)
prefer-dedupe=true

# Strict engine checks
engine-strict=true

Bash: automated dependency conflict diagnosis

#!/bin/bash
# Input:  Run in project root with package.json
# Output: Conflict report with fix suggestions

echo "=== npm Dependency Conflict Diagnosis ==="
echo "npm version: $(npm --version)"
echo "node version: $(node --version)"
echo ""

echo "--- Peer dependency check ---"
npx check-peer-dependencies 2>/dev/null || echo "(install: npm i -g check-peer-dependencies)"
echo ""

echo "--- Duplicate packages ---"
npm ls --all 2>&1 | grep "deduped" | sort | uniq -c | sort -rn | head -10
echo ""

echo "--- Outdated packages ---"
npm outdated --long 2>/dev/null | head -20
echo ""

echo "--- Install dry run (conflicts) ---"
npm install --dry-run 2>&1 | grep -E "(ERESOLVE|peer|conflict|WARN)" | head -20

Anti-Patterns

Wrong: Using --force or --legacy-peer-deps as default

# BAD — hides real incompatibilities that cause runtime errors [src6, src7]
npm install --force
# or
npm config set legacy-peer-deps true  # global — affects ALL projects!
# Silences the error without fixing the conflict.

Correct: Diagnose first, then fix the root cause

# GOOD — understand the conflict, then fix it [src5, src6]
npm explain react            # see why each version is needed
npm install some-lib@latest  # update the conflicting package
# If no update available: add "overrides" to package.json

Wrong: Deleting package-lock.json on every conflict

# BAD — loses reproducibility, may introduce NEW conflicts [src6]
rm package-lock.json
npm install
# Different versions resolved every time. CI becomes non-deterministic.

Correct: Targeted lockfile regeneration

# GOOD — only regenerate when you've actually changed overrides/versions
rm -rf node_modules package-lock.json
npm install
git add package-lock.json && git commit -m "Regenerate lockfile after override change"

Wrong: Wildcard overrides without version constraint

// BAD — "*" means any version, including breaking majors [src1, src5]
{
  "overrides": {
    "lodash": "*"
  }
}

Correct: Pin to specific version or range

// GOOD — explicit version, predictable behavior [src1, src5]
{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Common Pitfalls

• --legacy-peer-deps masks runtime crashes: The flag installs packages that declare they need React 17 alongside your React 18. The package may call React 17-only APIs and crash at runtime. Always test thoroughly after using this flag. [src6]
• npm overrides silently ignored on old npm: The overrides field requires npm >= 8.3.0. Older versions skip it with no warning. CI runners often have stale npm versions. [src2, src5]
• Yarn resolutions ignored in workspace inner packages: Resolutions must be in the root package.json. A resolutions field in a workspace member's package.json is ignored for hoisted dependencies. [src3]
• Stale lockfile after override change: Adding overrides without deleting node_modules and the lockfile means the override is not applied. Always rm -rf node_modules package-lock.json && npm install. [src5]
• pnpm strict mode rejects all peer mismatches: pnpm does not auto-install conflicting peers. Use pnpm.peerDependencyRules.allowedVersions for intentional mismatches or ignoreMissing for optional peers. [src4]
• npm ci ignores overrides not in lockfile: npm ci installs from lockfile only. Changed overrides require regenerating package-lock.json first via npm install. [src5, src6]

Diagnostic Commands

# === Identify conflicts ===
npm ls --all 2>&1 | head -100          # full dependency tree
npm explain <package-name>              # trace dependency chain (alias: npm why)
npm outdated --long                     # list all outdated packages
npm install --dry-run 2>&1 | grep -E "ERESOLVE|peer|conflict"

# === Yarn equivalents ===
yarn why <package-name>
yarn list --pattern <package-name>

# === pnpm equivalents ===
pnpm why <package-name>
pnpm ls <package-name>

# === Fix commands ===
npm dedupe                              # reduce duplicate versions
npm dedupe --dry-run                    # preview changes
rm -rf node_modules package-lock.json   # clean slate
npm cache clean --force                 # clear npm cache
npm install                             # fresh install
npx check-peer-dependencies             # verify peer deps satisfied

# === Version checks ===
npm --version                           # need >= 8.3 for overrides
node --version                          # check engine compatibility

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• npm overrides vs yarn resolutions are NOT interchangeable: npm uses overrides (npm >= 8.3), Yarn uses resolutions. Including both is allowed but each tool only reads its own field. [src1, src3]
• --force and --legacy-peer-deps do different things: --force bypasses ALL safety checks (cache, checksums, peer deps). --legacy-peer-deps ONLY reverts peer dep behavior to npm 6 style. Always prefer --legacy-peer-deps if you must use a flag. [src6]
• Overrides apply to the entire dependency tree: An override like "react": "^18.2.0" forces EVERY package in the tree to use React 18.2+, even packages not tested with it. This can cause subtle runtime bugs. [src1, src5]
• pnpm resolves peers differently than npm/yarn: pnpm may create multiple copies of the same package version, each with different peer dependency sets. This is by design but can cause confusion when inspecting node_modules. [src4]
• Lock files are package-manager specific: package-lock.json (npm), yarn.lock (Yarn), pnpm-lock.yaml (pnpm) are NOT interchangeable. Mixing package managers causes phantom conflicts. Enforce one via engines or corepack. [src6]