DevToolBox

npm ERESOLVE エラーの原因と解決

最終更新日: 2026-04-19公開日: 2026-04-19執筆: DevToolBox編集部

npm ERR! ERESOLVE unable to resolve dependency tree は npm 7 以降のピア依存 自動解決に起因します。--legacy-peer-deps で逃げる前に、原因を特定してoverrides で固定するのが本筋です。

ERESOLVE comes from npm 7's strict peer dependency resolution. Avoid reaching for --legacy-peer-deps first — pin the conflict withoverrides instead.

TL;DR

1. エラーの読み方 / Read the error

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@19.0.0
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18" from some-lib@3.2.0

上の例は「some-lib@3.2.0 は React 18 を期待しているのに、アプリが React 19 を 入れている」という衝突。解決策は 3 択です。

2. 解決策 3 パターン / Three ways to fix

方法 / Option向き不向き例
ライブラリを上げる最良。メンテ続けるなら必ずこれsome-lib@latest に更新
overrides で固定ライブラリ側が追従しない場合下記コード参照
--legacy-peer-deps一時的な CI パス用。本番NG.npmrc に書くと伝染する

3. overrides の書き方 / Using overrides

// package.json
{
  "overrides": {
    "some-lib": {
      "react": "19.0.0"
    }
  }
}

some-lib から見える React だけ上書きします。トップレベルの React バージョンは 変えないのがミソ。yarn の場合は resolutions、pnpm の場合はpnpm.overrides。

4. 再発予防 / Prevention

5. パッケージマネージャーによる挙動の違い / Behavior differs by package manager

ツール / Toolpeer dependency の扱い
npm 7+自動インストール。バージョン不整合はデフォルトでエラー(ERESOLVE)
npm 6以前peer dependencyを自動インストールせず警告のみ(エラーにならない)
Yarn Classic (v1)警告のみで自動解決はしない(npm 6に近い挙動)
Yarn Berry (v2+)Plug'n'Play等の仕組みで厳密だが、resolutionsで個別に固定可能
pnpmデフォルトで峻厳。pnpm.overridesや.npmrcの設定で緩和可能

--legacy-peer-depsは実質的にnpm 6相当の緩い挙動へ戻すオプションです。 頻繁にERESOLVEに悩まされるなら、そもそもnpm 6時代のような緩さが不要なプロジェクトかどうかを 見直す機会でもあります。

6. npm ci ではロックファイルの整合性がより厳しく問われる / npm ci is stricter

CI環境で使うnpm ciは、node_modulesを一度削除してからpackage-lock.json通りに再構築します。ローカルで--legacy-peer-depsやoverridesを使ってERESOLVEを解決した場合、その結果が反映されたpackage-lock.jsonを必ずコミットしておく必要があります。

# ローカルで解決 → package-lock.json が更新される
npm install --legacy-peer-deps
git add package-lock.json
git commit -m "fix: pin peer dependency conflict"

# CIではこのpackage-lock.jsonの内容通りにインストールされる
npm ci

package-lock.jsonをコミットし忘れると、CIだけ古い依存関係グラフから インストールを試みて再びERESOLVEで落ちる、という食い違いが起きやすいので注意してください。

7. overridesの応用:自分のバージョンと連動させる / Referencing your own dependency version

overridesでバージョンを直接書くと、アップデートのたびに2箇所を書き換える必要が 出てきます。$構文を使うと、トップレベルのdependenciesに書いた バージョンをそのまま参照でき、二重管理を避けられます。

// package.json
{
  "dependencies": {
    "react": "19.0.0"
  },
  "overrides": {
    "some-lib": {
      "react": "$react"
    }
  }
}

$reactは「このpackage.jsonのdependenciesに書かれているreactと 同じバージョンを使う」という意味です。reactを19.1.0にアップデートする際も、overrides側を書き換え忘れる心配がなくなります。

8. English summary

ERESOLVE is npm 7's strict peer-dependency check surfacing a real conflict. Read the error to find which package expected which version, then fix in this order: (1) upgrade the offending library, (2) pin with overrides inpackage.json, (3) as a last resort, use--legacy-peer-deps. Never persist --legacy-peer-deps in.npmrc for production — it masks real runtime mismatches.

よくある質問 / FAQ

npm install で ERESOLVE が出るのはなぜ?
npm 7 以降は peerDependencies を自動インストールし、バージョン不整合をエラー扱いします。依存のどこかで React 18 系と 19 系が競合している、といった状況が典型です。
Why does npm throw ERESOLVE?
npm 7+ installs peerDependencies automatically and fails on version conflicts — typically two packages that want incompatible versions of React, TypeScript, etc.
--legacy-peer-deps は安全?
一時しのぎには有効ですが、実行時エラーを覆い隠すので本番投入前に overrides で正しく固定するのが推奨です。

関連ツール / Related tools

関連ガイド / Related guides