You run pnpm install and get hit with:

 WARN  Issues with peer dependencies found
.
└─┬ some-package
  └── ✕ missing peer react@"^18.0.0"

This is one of the most common pnpm warnings, and it trips people up because npm and Yarn silently ignore it by default. pnpm doesn’t.

What causes this

pnpm enforces strict peer dependency resolution out of the box. When a package declares a peer dependency (e.g., a React component library that expects react to be installed by the consumer), pnpm checks that the peer is actually present in your project and that the version satisfies the declared range.

npm auto-installs peers since v7, and Yarn mostly ignores mismatches. pnpm takes the stricter approach — which is actually correct behavior. The package author is telling you “I need this to work properly,” and pnpm respects that.

You’ll see this when:

• You install a library that depends on a framework you haven’t added yet
• Your installed version of the peer doesn’t match the required range
• You’re migrating a project from npm/Yarn to pnpm

Fix 1: Install the missing peer dependency

The most straightforward fix. Read the warning — it tells you exactly what’s missing and what version range is expected.

pnpm add react@^18.0.0 react-dom@^18.0.0

Check the warning output carefully. Sometimes multiple packages need the same peer, and the version ranges might conflict. In that case, you need to find a version that satisfies all of them.

Fix 2: Auto-install peers via .npmrc

If you want pnpm to behave more like npm v7+ and automatically install peer dependencies, add this to your .npmrc at the project root:

# .npmrc
auto-install-peers=true

This tells pnpm to automatically install missing peers. It picks the best matching version based on the declared range. This is a good default for most projects.

After adding this, run:

pnpm install

Fix 3: Relax strict peer dependency checks

If you’re dealing with version mismatches that you know are safe (e.g., a library declares react@^17 but works fine with React 18), you can disable the strict check:

# .npmrc
strict-peer-dependencies=false

This turns the errors into warnings. The install will succeed, but you’ll still see the warnings. Use this when you’ve verified compatibility yourself — don’t just slap it in to make errors go away.

Fix 4: Override a peer dependency version

When two packages demand conflicting peer versions, use pnpm’s overrides to force a specific version:

{
  "pnpm": {
    "overrides": {
      "react": "^18.2.0"
    }
  }
}

Add this to your package.json. This forces every package in the dependency tree to use the specified version of react, regardless of what they declare.

Related resources

• pnpm cheat sheet
• pnpm vs npm
• npm cheat sheet

How to prevent it

• Add auto-install-peers=true to .npmrc in new projects from the start
• When adding a UI library, check its peerDependencies in the package.json before installing
• Run pnpm install in CI with --frozen-lockfile to catch peer issues early
• Keep your .npmrc in version control so the whole team uses the same settings