pnpm v9 でインストールが失敗する・ピア依存関係エラーが解消できない時の原因と対処法【ERR_PNPM_PEER_DEP_ISSUES】

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

pnpm v9 でインストールが突然失敗する症状

pnpm を v8 から v9 にアップグレードした途端、今まで問題なく通っていた pnpm install がエラーで終了するようになった——この症状に遭遇した方は多いはずです。CI で突然ビルドが落ちたケースも多く報告されています。

具体的な症状：

• pnpm install が途中で止まり ERR_PNPM_PEER_DEP_ISSUES が出る
• v8 では問題なく動いていたのに v9 では失敗する
• GitHub Actions などの CI でパイプラインが突然レッドになる
• pnpm add で新しいパッケージを追加しようとしても失敗する

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

 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.

結論から言うと： これは pnpm v9 で strict-peer-dependencies のデフォルト値が false から true に変更されたことが原因です。

原因：pnpm v9 の破壊的変更

pnpm v9（2024年4月リリース）では、いくつかの破壊的変更が導入されました。その中でも最もインパクトが大きかったのが strict-peer-dependencies のデフォルト変更です。

strict-peer-dependencies とは何か

npm や yarn では長らく「ピア依存関係の不一致は警告（warning）止まり」でした。pnpm v8 でも同様に strict-peer-dependencies=false がデフォルトだったため、バージョンが合わなくてもインストールは成功していました。

pnpm v9 では ピア依存関係の不一致をエラー（error）として扱うようになり、インストールが失敗するようになりました。

ピア依存関係のミスマッチが起きやすい典型的な状況：

• React 19 にアップグレードしたが、一部のライブラリがまだ React 18 以下しか対応していない
• TypeScript 5.x を使っているが、古いプラグインが peerDependencies に "typescript": "^4" と書いている
• Storybook・ESLint プラグインなど、peerDependencies の宣言が古いままのエコシステム系ライブラリ

対処法1：.npmrc で strict-peer-dependencies を無効にする（最速の一時対応）

最も手軽な対処です。プロジェクトルートの .npmrc ファイルに以下の1行を追加します：

strict-peer-dependencies=false

.npmrc ファイルがない場合は新規作成してください。この設定により pnpm v8 と同様の動作に戻ります。

メリット： 1行で即解決、既存コードの変更不要 デメリット： 根本解決ではない。本来は問題のある依存関係が存在したままになる

CI での注意： CI 環境変数で上書きしたい場合は npm_config_strict_peer_dependencies=false を環境変数に設定するか、pnpm install --no-strict-peer-dependencies とコマンドに直接指定します。

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

対処法2：peerDependencyRules で特定パッケージだけ抑制する（推奨）

プロジェクト全体で strict チェックを無効にするのではなく、問題のある特定パッケージのみを対象に抑制する方法です。package.json の pnpm フィールドを使います。

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [
        "react",
        "react-dom"
      ],
      "allowAny": [
        "typescript"
      ]
    }
  }
}

例：Storybook と React 19 の組み合わせ

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

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["react", "react-dom"]
    }
  }
}

例：TypeScript 5.x と古いプラグイン

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "typescript": "5"
      }
    }
  }
}

対処法3：overrides でバージョンを強制解決する

推移的依存関係（間接的に依存しているパッケージ）のバージョンを強制的に上書きしたい場合は pnpm.overrides を使います。

{
  "pnpm": {
    "overrides": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    }
  }
}

これにより、依存グラフ全体で該当パッケージのバージョンが強制的に統一されます。ピア依存関係の要求が一致するため、エラーが解消されます。

注意： overrides は本来互換性のないバージョンを強制するため、ランタイムエラーが別途発生する可能性があります。変更後は必ずテストを実行してください。

対処法4：問題のあるパッケージ自体をアップデートする（根本解決）

エコシステムが追いついている場合、問題のあるパッケージをアップデートすることで peerDependencies の宣言が新しいバージョンに対応します。

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

# 特定パッケージをアップデート
pnpm update storybook@latest @storybook/react@latest

# patch/minor 範囲で一括アップデート
pnpm update --recursive

Storybook の場合は v8 以降で React 19 への対応が進んでいるため、storybook@latest にアップデートするのが最善策です。

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

pnpm v9 へのアップグレード手順（新規プロジェクト向け）

既存プロジェクトを v8 から v9 に移行する場合の推奨手順です：

# 1. pnpm 自体をアップデート
npm install -g pnpm@latest
# または
corepack use pnpm@latest

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

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

# 4. エラー内容を確認して peerDependencyRules を設定する
# package.json に pnpm.peerDependencyRules を追加

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

package.json で packageManager フィールドを指定しておくと、チームメンバーや CI が同じバージョンを使うことを強制できます：

{
  "packageManager": "pnpm@9.15.0"
}

まとめ

pnpm v9 の ERR_PNPM_PEER_DEP_ISSUES は、strict-peer-dependencies のデフォルトが false から true に変わったことで、今まで黙認されていたピア依存関係の不一致がエラーとして顕在化したものです。

状況別の推奨対処：

1. 今すぐ動かしたい（一時対応） → .npmrc に strict-peer-dependencies=false
2. 特定パッケージだけ問題（ピンポイント） → package.json の pnpm.peerDependencyRules
3. 依存バージョンを統一したい → pnpm.overrides で強制解決
4. 根本解決したい → 問題パッケージを最新版にアップデート

peerDependencyRules と overrides を組み合わせることで、プロジェクト全体の strict チェックを維持しながら、特定の不可避な不一致だけを選択的に許容する設定が組めます。CI の安定性のためにも、早めに .npmrc での一時対応から peerDependencyRules による明示的な管理に移行することをおすすめします。

技術ブログの記事一覧へ