← Cheatsheets / Error Fixes

How to Fix npm/pip Dependency Conflicts

Getting dependency version conflicts, peer dependency warnings, or pip resolver errors? Here's how to fix dependency conflicts in JavaScript and Python projects.

npm pip dependencies debugging error-fix

You ran npm install or pip install and got a wall of red text about conflicting versions. Dependency conflicts happen when two packages need different, incompatible versions of the same dependency.

AI tools cause these constantly — they add packages without checking what’s already installed, or suggest outdated versions that clash with your existing stack.

What Do Dependency Conflicts Mean?

In plain English: “Two packages need different versions of the same thing, and they can’t both win.”

Package A needs react@18. Package B needs react@17. You can only have one version of React. Conflict.

Common Error Messages

# npm
npm ERR! ERESOLVE could not resolve
npm WARN peer dep missing: react@^17.0.0, required by [email protected]
npm ERR! Could not resolve dependency: peer react@"^17.0.0"

# pip
ERROR: pip's dependency resolver does not currently have a way to resolve...
ERROR: Cannot install package-a==2.0 and package-b==3.0 because these
package versions have conflicting dependencies.

# yarn
error An unexpected error occurred: "[email protected]" has unmet peer dependency

4 Common Causes

1. Outdated Package Needs Old Peer Dependency

A package hasn’t updated to support the latest version of React, Next.js, etc.

# Error: some-ui-lib needs react@^17.0.0 but you have [email protected]

# Fix: check if there's a newer version that supports React 18
npm info some-ui-lib versions
npm install some-ui-lib@latest

2. AI Mixed Incompatible Packages

AI added packages from different eras that don’t work together.

# AI installed both:
npm install next@14 react@17  # ← Next.js 14 needs React 18!

# Fix: let the framework dictate core deps
npm install next@14 react@18 react-dom@18

3. Lockfile Out of Sync

Your package-lock.json or yarn.lock says one thing, package.json says another.

# Nuclear option — regenerate lockfile
rm package-lock.json    # or yarn.lock
rm -rf node_modules
npm install

4. Python Virtual Environment Pollution

You’ve installed conflicting packages across multiple projects into the global Python.

# Fix: use a fresh virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step-by-Step Fix Process

JavaScript (npm)

Step 1: Understand the conflict

npm ls react          # see all packages that depend on react
npm explain react     # detailed dependency chain

Step 2: Try updating the conflicting package

npm install conflicting-package@latest

Step 3: If that doesn’t work, force resolution

# npm 8+ — use --legacy-peer-deps to ignore peer conflicts
npm install --legacy-peer-deps

# Or add overrides to package.json to force a version:
{
  "overrides": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  }
}

Step 4: Nuclear reset

rm -rf node_modules package-lock.json
npm install

Python (pip)

Step 1: Identify the conflict

pip check                    # shows broken dependencies
pipdeptree                   # visual dependency tree (pip install pipdeptree)

Step 2: Try installing with flexible versions

# Instead of pinning exact versions:
pip install "package-a>=2.0,<3.0" "package-b>=1.5"

Step 3: Use a constraint file

# constraints.txt — force specific versions
numpy==1.24.0
pandas==2.0.0

pip install -r requirements.txt -c constraints.txt

Step 4: Fresh environment

deactivate
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

npm-Specific Solutions

Package Overrides (npm 8+)

// package.json — force all sub-dependencies to use your version
{
  "overrides": {
    "some-problematic-dep": "2.0.0"
  }
}

Yarn Resolutions

// package.json — yarn equivalent
{
  "resolutions": {
    "react": "18.3.0",
    "some-package/dependency": "2.0.0"
  }
}

pnpm Overrides

// package.json
{
  "pnpm": {
    "overrides": {
      "react": "18.3.0"
    }
  }
}

pip-Specific Solutions

# Install pip-tools
pip install pip-tools

# Write your direct dependencies in requirements.in
echo "flask>=3.0" > requirements.in
echo "sqlalchemy>=2.0" >> requirements.in

# Compile a locked, conflict-free requirements.txt
pip-compile requirements.in

# Install from the compiled file
pip install -r requirements.txt

Using Poetry

# Poetry handles dependency resolution automatically
poetry add flask sqlalchemy
poetry install

🤖 Prompt to Fix This

I'm getting dependency conflicts when installing packages:

[PASTE THE FULL ERROR OUTPUT]

Here's my package.json (or requirements.txt):

[PASTE DEPENDENCY LIST]

I'm using: [npm/yarn/pnpm/pip] with [Node version / Python version]

Please:
1. Explain which packages are conflicting and why
2. Tell me which package to update or replace
3. Give me the exact commands to fix this
4. If I need overrides/resolutions, show the exact config
5. Should I consider replacing any of these packages?

Prevention Tips

  1. Let AI see your package.json before adding dependencies — “Here are my current deps, add X without conflicts”
  2. Update regularly — small, frequent updates are easier than big jumps
  3. Use npx npm-check-updates to see what’s outdated before it becomes a problem
  4. Pin Python environments — always use venv, never install globally
  5. Don’t mix package managers — pick npm, yarn, or pnpm and stick with it
✓ Copied to clipboard!