ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies の直し方:pnpm install が失敗する原因と対処法【Mac・Windows・VS Code 共通 / peerDependencyRules / pnpm v9〜v11】

公開日:2026-10-01/カテゴリ:Node.js・pnpm・フロントエンド・CI/CD/AnchorUp 技術ブログ

pnpm install が ERR_PNPM_PEER_DEP_ISSUES で失敗する症状

pnpm install が ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies で止まる時は、ピア依存関係の不一致があり、しかも strict-peer-dependencies が true になっているのが原因です。pnpm の既定値は false なので、どこかで true に設定されています。

具体的な症状:

典型的なエラーログはこのような形です:

 ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

your-project@0.0.0:
└─┬ storybook@7.6.0
  ├── ✕ unmet peer react@"^16.8.0 || ^17.0.0 || ^18.0.0": found 19.0.0
  └── ✕ unmet peer react-dom@"^16.8.0 || ^17.0.0 || ^18.0.0": found 19.0.0

Peer dependencies that should be installed:
  react-dom@"^16.8.0 || ^17.0.0 || ^18.0.0"

hint: If you want to proceed with the installation in spite of this, use the --no-strict-peer-dependencies option, or set the strict-peer-dependencies setting to false in your .npmrc file.
 ELIFECYCLE  Command failed with exit code 1.

strict-peer-dependencies が false(既定値)の場合、同じ不一致があっても次のような警告が出るだけで、インストールは成功します。

 WARN  Issues with peer dependencies found
.
└─┬ storybook 7.6.0
  └── ✕ unmet peer react@"^16.8.0 || ^17.0.0 || ^18.0.0": found 19.0.0

つまり「警告で済む環境」と「エラーで止まる環境」の違いは、ピア依存関係そのものではなく strict-peer-dependencies の値です。

Mac・Windows・VS Code のターミナルで出る時も原因は同じです。 このエラーは pnpm が依存関係を解決する段階で出るもので、OS やエディタに固有の原因はありません。違いが出るのは「どの設定ファイルが読まれるか」だけで、たとえばホームディレクトリの .npmrc は Windows では %USERPROFILE%\.npmrc にあります。VS Code のターミナルだけで失敗する場合は、そのターミナルで pnpm --version を実行し、別の場所にある古い pnpm が使われていないかを確認してください。

なぜ ERR_PNPM_PEER_DEP_ISSUES で止まるのか?strict-peer-dependencies が true になっている

結論: ERR_PNPM_PEER_DEP_ISSUES は、strict-peer-dependencies が true の時にだけ出るエラーです。pnpm 公式ドキュメントの説明も「プロジェクトに解決されていないピア依存関係がある場合、またはピア依存関係が要求範囲に一致しない場合に pnpm install は失敗する」で、直し方は「足りないピア依存関係をインストールする」か「peerDependencyRules で個別に無視する」の2つです。

strict-peer-dependencies の既定値はバージョンでどう変わったか

「pnpm v9 で既定値が true になった」と説明されることがありますが、これは誤りです。pnpm の GitHub Releases では次のように変わっています。

pnpm のバージョン strict-peer-dependencies の既定値 根拠
v7.0.0 〜 v7.13.4 true v7.0.0 の破壊的変更で true に変更
v7.13.5 以降(v8 / v9 / v10 / v11 も含む) false v7.13.5 のリリースノート「strict-peer-dependencies is set to false by default」

v9.0.0 の破壊的変更の一覧にも strict-peer-dependencies の既定値の変更はありません。現行ドキュメント(Settings → Peer Dependency Settings)でも strictPeerDependencies の既定値は false です。

どこで strict-peer-dependencies が有効になるのか

既定値が false なのにエラーになるなら、次のどれかで true になっています。

設定場所 書き方の例 見落としやすい点
プロジェクトの .npmrc strict-peer-dependencies=true pnpm v7 時代に書いたまま残っている。v11 では .npmrc からは認証・レジストリ設定しか読まれない
pnpm-workspace.yaml strictPeerDependencies: true v10.5 以降はここに pnpm の設定を書ける。v11 ではここが本来の場所
ホームディレクトリの設定 ~/.npmrc など 自分の PC だけ、または CI イメージだけで有効になっている
コマンドの引数 pnpm install --strict-peer-dependencies CI のワークフローや Makefile に書かれている
環境変数 npm_config_strict_peer_dependencies=true v11 では npm_config_* は読まれず pnpm_config_* になる
pnpm v7.0〜v7.13.4 を使っている (設定なし) packageManager や CI の pnpm バージョンが古い

strict-peer-dependencies を有効にしている場所を探すには

次のコマンドで、設定ファイルと環境変数をまとめて確認できます。

# 1. pnpm のバージョン(v7.13.4 以前なら既定で true)
pnpm --version

# 2. プロジェクトとホームの設定ファイル
grep -n -i "strict-peer-dependencies\|strictPeerDependencies" \
  .npmrc pnpm-workspace.yaml package.json ~/.npmrc 2>/dev/null

# 3. 環境変数(CI のログでも同じものを確認する)
env | grep -i "strict_peer"

# 4. CI のワークフローに引数で書かれていないか
grep -rn "strict-peer-dependencies" .github/ 2>/dev/null

何も見つからないのに失敗する場合は、CI で使っている pnpm のバージョンと package.json の packageManager を確認してください。

pnpm v8 → v9 に上げた後に失敗し始めるのはなぜか?

結論: v9 で既定値が変わったのではなく、ピア依存関係の解決方法が変わり、不一致として報告されるものが増えたことが主な理由です。strict-peer-dependencies が true の環境では、それがそのままインストール失敗になります。

v9.0.0 のリリースノートにある、ピア依存関係に関わる変更は次のとおりです。

変更 影響
自分自身もピア依存関係を持つパッケージのピア依存関係を正しく解決するようになった(#7444, #7606) v8 で見逃されていた不一致が報告される
オプションのピア依存関係を依存グラフ内のどのパッケージからでも解決するようになった(#7830) 解決されるバージョンが変わることがある
packageManager フィールドと違うバージョンの pnpm では実行しない CI と手元で pnpm のバージョンが違うと止まる

v8 と v9 の主な既定値・要件はこうなっています。

設定項目 v8 v9
strict-peer-dependencies false false(変更なし)
auto-install-peers true true(変更なし)
サポートする Node.js v16.14 以上 v18 以上

エラーログの読み方:unmet peer と missing peer の違い

ログの ✕ の後ろの言葉で、選ぶ対処が変わります。

ログの表示 意味 対処
✕ unmet peer react@"^18.0.0": found 19.0.0 ピア依存関係は入っているが、要求範囲とバージョンが合わない パッケージを更新する、または allowedVersions / allowAny
✕ missing peer react@"^18.0.0" ピア依存関係がインストールされていない 足りないパッケージを追加する、または ignoreMissing
Peer dependencies that should be installed: 追加すべきピア依存関係の一覧 表示されたパッケージを pnpm add する

ピア依存関係の不一致が起きやすい典型的な状況:

auto-install-peers が true なのに ERR_PNPM_PEER_DEP_ISSUES が出るのはなぜ?

結論: auto-install-peers(既定値 true)が自動で入れるのは、どこにも入っていない(missing)、optional ではないピア依存関係だけです。すでに別のバージョンが入っている ✕ unmet peer や、複数のパッケージが食い違う範囲を要求しているピア依存関係は自動では解決されません。そのため「自動で入るはずなのに止まる」ことが起きます。

pnpm 公式ドキュメント(Settings → Peer Dependency Settings)の説明は、「true の場合、足りない optional ではないピア依存関係は自動でインストールされる」「異なるパッケージからピア依存関係に食い違うバージョン要求がある場合、pnpm はそのピア依存関係のどのバージョンも自動ではインストールせず、警告を表示する」です。

ケース auto-install-peers で解決されるか ログに出る形
ピア依存関係がどこにも入っておらず、要求範囲が1つだけ される(範囲を満たす最も新しいバージョンが入る) 出ない
自分で dependencies に書いたバージョンが要求範囲の外 されない(自分で書いたバージョンが優先される) ✕ unmet peer ...: found x.y.z
2つ以上のパッケージが重ならない範囲を要求している(例:^17 と ^18) されない(どちらか一方を選べないため) ✕ unmet peer または ✕ missing peer
optional なピア依存関係(peerDependenciesMeta で optional: true) ワークスペースに範囲を満たすバージョンがある時だけ 通常は出ない

範囲が食い違う時はどう直すのか?

2つのパッケージが react@^17 と react@^18 のように重ならない範囲を要求している場合、pnpm には正解のバージョンを決められません。公式ドキュメントでも「どのバージョンを入れるかを自分で判断するか、依存関係を更新して要求をそろえる」と案内されています。手順は次のとおりです。

  1. ログのツリーで、どのパッケージがどの範囲を要求しているかを確認する(次の節のコマンドも使う)
  2. 使うバージョンを決めて、package.json の dependencies に明示的に書く
  3. 古い範囲を要求しているパッケージを更新できるか確認する(対処法4)
  4. 更新できない場合だけ、そのパッケージに絞って allowedVersions で許可する(対処法2)
# 使うバージョンを自分で決めて、直接の依存関係として入れる
pnpm add react@^18 react-dom@^18

どのパッケージがピア依存関係の不一致を起こしているか調べるには?

結論: エラーログのツリーで ✕ の1つ上に出ているパッケージが、その範囲を要求している側です。pnpm v11 なら pnpm peers check で lockfile から不一致を一覧でき、どの経路で入ったかは pnpm why で調べられます。

# pnpm v11:lockfile を読んで unmet / missing peer を一覧する(問題があると exit code 1)
pnpm peers check

# JSON で出力する(CI のログ解析やスクリプト用)
pnpm peers check --json

# ワークスペースの全プロジェクトを調べる
pnpm peers check -r

# そのパッケージがどの依存関係の経路で入っているかを調べる(バージョンを問わず使える)
pnpm why react

# pnpm v10 以前:strict を外してインストールし、出てきた警告を一覧として読む
pnpm install --no-strict-peer-dependencies

pnpm peers check は v11 のドキュメントに載っているコマンドで、v10 のドキュメントにはありません。node_modules に前回のインストール時の lockfile があればそれを、無ければ pnpm-lock.yaml を読むので、インストールし直さずに確認できます。--lockfile-only を付けると常に pnpm-lock.yaml を読みます。

問題があると exit code 1 で終わるため、strict-peer-dependencies を true にしなくても、CI に1ステップ足すだけでピア依存関係の不一致を検出できます。「インストールは止めたくないが、不一致には気づきたい」場合に向いています。

# GitHub Actions での例(pnpm v11)
- name: Install dependencies
  run: pnpm install --frozen-lockfile

- name: Check peer dependencies
  run: pnpm peers check

対処法1:strict-peer-dependencies を false に戻す(最速の一時対応)

一番手軽な対処は、true にしている設定を消すか false にすることです。既定値に戻るので、不一致は警告として表示されるだけになります。

pnpm v10 以降は pnpm-workspace.yaml に書きます(v11 ではここが必須)。

# pnpm-workspace.yaml
strictPeerDependencies: false

pnpm v9 以前は .npmrc に書きます。

# .npmrc(pnpm v9 以前)
strict-peer-dependencies=false

メリット: 1行で直る。コードの変更は不要 デメリット: 根本解決ではない。不一致のある依存関係はそのまま残る

CI での注意: コマンドで指定する場合は pnpm install --no-strict-peer-dependencies を使います。環境変数で指定する場合、pnpm v10 以前は npm_config_strict_peer_dependencies=false、v11 以降は pnpm_config_* の名前にします。

# GitHub Actions での例
- name: Install dependencies
  run: pnpm install --no-strict-peer-dependencies

対処法2:peerDependencyRules で特定パッケージだけ許可する(推奨)

結論: プロジェクト全体の strict チェックは残したまま、問題のあるパッケージだけを許可する方法です。公式ドキュメントでも ERR_PNPM_PEER_DEP_ISSUES の対処として案内されています。

pnpm v10.5 以降は pnpm-workspace.yaml に書けます。v11 では package.json の pnpm フィールドが読まれなくなったので、v11 では必ず pnpm-workspace.yaml に書きます。

# pnpm-workspace.yaml(pnpm v10.5 以降)
peerDependencyRules:
  ignoreMissing:
    - react
    - react-dom
  allowAny:
    - typescript

pnpm v9 以前は package.json の pnpm フィールドに書きます。

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react", "react-dom"],
      "allowAny": ["typescript"]
    }
  }
}
キー 説明 使う場面
ignoreMissing 指定したパッケージがピア依存関係として入っていないことを報告しない ✕ missing peer
allowAny 指定したパターンに一致するピア依存関係は、どのバージョンでも許可する ✕ unmet peer(範囲を問わず許可)
allowedVersions 指定した範囲のバージョンなら不一致として報告しない ✕ unmet peer(範囲を絞って許可)

例:Storybook 7 と React 19 の組み合わせ

Storybook v7 系は peerDependencies に "react": "^16.8.0 || ^17.0.0 || ^18.0.0" と書いており、React 19 を使うプロジェクトでは ✕ unmet peer になります。

# pnpm-workspace.yaml
peerDependencyRules:
  allowAny:
    - react
    - react-dom

例:特定のパッケージにだけ TypeScript 5 を許可する

allowedVersions は 親パッケージ>ピア依存関係 の形で、対象を1つのパッケージに絞れます(old-ts-plugin は例です)。

# pnpm-workspace.yaml
peerDependencyRules:
  allowedVersions:
    "old-ts-plugin>typescript": "5"

対処法3:overrides でバージョンをそろえる

推移的依存関係(間接的に依存しているパッケージ)のバージョンを強制的にそろえたい場合は overrides を使います。v10.5 以降は pnpm-workspace.yaml に、v9 以前は package.json の pnpm.overrides に書きます。

# pnpm-workspace.yaml
overrides:
  react: ^19.0.0
  react-dom: ^19.0.0
{
  "pnpm": {
    "overrides": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    }
  }
}

依存グラフ全体でバージョンがそろうので、ピア依存関係の要求と実際のバージョンが一致します。

注意: overrides は互換性のないバージョンを強制することがあるので、別のランタイムエラーが起きる可能性があります。変更後は必ずテストを実行してください。

対処法4:問題のあるパッケージを更新する(根本解決)

ライブラリ側が新しいバージョンに対応していれば、パッケージを更新するのが一番確実です。

# どのパッケージに更新があるか確認
pnpm outdated

# 特定パッケージを更新
pnpm update storybook@latest @storybook/react@latest

# patch/minor 範囲で一括更新
pnpm update --recursive

Storybook の場合は v8 以降で React 19 への対応が進んでいるため、storybook@latest に上げるのが最善です。

よくある症状と原因・対処の早見表

症状・エラーの内容 原因 推奨対処
✕ unmet peer react@"^18.0.0": found 19.0.0 React 19 と古いライブラリの組み合わせ パッケージ更新 / allowAny
✕ unmet peer typescript@"^4" TypeScript 5.x と古いプラグイン パッケージ更新 / allowedVersions
✕ missing peer ... ピア依存関係がインストールされていない pnpm add で追加 / ignoreMissing
手元は警告だけで CI だけ失敗する CI の引数・環境変数・設定で strict が有効、または CI の pnpm が古い 設定場所を探して外す / pnpm のバージョンをそろえる
pnpm v8 → v9 に上げた直後に失敗する ピア依存関係の解決方法が変わり、不一致が増えた(strict が true の時だけ失敗) ログを読み、更新か peerDependencyRules
auto-install-peers が true なのに失敗する 自分で書いたバージョンが範囲外、または複数のパッケージの要求範囲が食い違っている 使うバージョンを決めて dependencies に書く / パッケージ更新
どのパッケージが原因か分からない ログのツリーが長い・ワークスペースが多い v11 は pnpm peers check、経路は pnpm why
v11 に上げたら peerDependencyRules が効かなくなった package.json の pnpm フィールドが読まれなくなった pnpm-workspace.yaml に移す

pnpm を上げる時の手順

既存プロジェクトで pnpm のメジャーバージョンを上げる時の手順です。

# 1. pnpm 自体を更新
corepack use pnpm@latest
# または
npm install -g pnpm@latest

# 2. バージョン確認
pnpm --version

# 3. まず --no-strict-peer-dependencies でインストールし、どこが問題か把握する
pnpm install --no-strict-peer-dependencies

# 4. 警告の内容を見て、パッケージ更新か peerDependencyRules を設定する

# 5. 通常の pnpm install が通ることを確認
pnpm install

package.json の packageManager フィールドで pnpm のバージョンを固定しておくと、チームメンバーや CI が同じバージョンを使います。手元と CI でバージョンが違うことによる「CI だけ失敗する」も防げます。

{
  "packageManager": "pnpm@9.15.0"
}

pnpm 特有の厳密さで起きる別のエラーとしては、package.json に書いていない依存関係が見つからなくなる「幽霊依存」もあります。詳しくは pnpm で Cannot find module になる原因:phantom dependency とは を参照してください。

まとめ

ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies は、ピア依存関係の不一致がある状態で strict-peer-dependencies が true になっている時に出るエラーです。既定値は v7.13.5 以降ずっと false なので、まずどこで true にしているかを探すのが近道です。

状況別の推奨対処:

  1. 今すぐ動かしたい(一時対応) → strictPeerDependencies: false(v9 以前は .npmrc の strict-peer-dependencies=false)か --no-strict-peer-dependencies
  2. 特定パッケージだけ問題 → peerDependencyRules(unmet peer は allowedVersions / allowAny、missing peer は ignoreMissing)
  3. 依存バージョンをそろえたい → overrides
  4. 根本解決したい → 問題のパッケージを最新版に更新

pnpm v11 では package.json の pnpm フィールドと .npmrc の大半の設定が読まれなくなりました。v11 に上げる時は、peerDependencyRules・overrides・strictPeerDependencies を pnpm-workspace.yaml に移してください。

技術ブログの記事一覧へ