「npm installで失敗する原因と対処法｜依存関係エラーの基本対応」

2026年5月15日

「npm install」で失敗したときの原因と対処法｜依存関係エラーの基本対応

npm install が失敗するとき、最初に疑うべきなのは 依存関係の競合、Node.js / npm の版ずれ、package-lock.json と実際の状態の不一致 です。むやみに node_modules を消す前に、どの種類の失敗なのかを切り分けると、復旧がかなり早くなります。

実務では、ローカルでは入るのに CI で落ちる、チームメンバーごとに結果が違う、古いプロジェクトだけ ERESOLVE が出る、といった形で詰まりやすいです。この記事では、初心者でも再現しやすい確認手順と、よくある依存関係エラーの基本対応をまとめます。

ここがポイント: npm install の失敗は「何でも再インストール」で片づけず、エラーの種類を見て、環境・ロックファイル・依存定義のどこがズレているか を先に確認すると解決しやすくなります。

すぐ確認したい点は node -v、npm -v、package-lock.json の有無、エラーコードです
ERESOLVE は依存関係、特に peerDependencies の衝突を疑います
CI や本番用の再現性を優先するなら npm ci のほうが向いています
npm cache clean --force は最後の手段で、先に npm cache verify を試すのが基本です

まず把握したい前提環境

同じ package.json でも、Node.js や npm の版が違うと結果が変わります。ここを飛ばすと、直したつもりでも別の環境でまた落ちます。

2026年4月22日時点で、Node.js 公式は本番用途では LTS 系列の利用を勧めています。公式のリリース一覧では、v24 が LTS、v22 と v20 も LTS 系列として掲載されています。日常的な開発で odd 番の Current 系列を使っていると、古いプロジェクトで差が出ることがあります。

最初に次を確認してください。

node -v
npm -v
npm config get registry

確認ポイントは次の通りです。

プロジェクトの README や .nvmrc に指定された Node.js 版と一致しているか
package.json の engines に Node.js / npm の条件があるか
会社やチームで private registry を使っていないか
ローカルと CI で npm のメジャーバージョンがズレていないか

`npm install` でよくある失敗原因

ここでは、特に頻度の高いものから見ます。

1. `peerDependencies` の競合

npm v7 以降は peerDependencies をより厳密に扱うため、以前は通っていた構成でも ERESOLVE で止まることがあります。

たとえば、あるパッケージが React 18 を要求し、別のパッケージが React 17 までしか受け付けないと、npm は依存関係を安全に解決できず失敗します。

典型例です。

{
  "dependencies": {
    "react": "18.2.0",
    "some-plugin": "1.0.0"
  }
}

この some-plugin 側が peerDependencies で react: ^17 を要求していると、npm install が失敗することがあります。

対処の優先順は次です。

まず、競合しているパッケージ同士の対応バージョンを確認する
片方を上げるか下げるかを決めて、依存関係をそろえる
依存の理由を npm explain <package名> や npm ls <package名> --all で追う
どうしても必要なときだけ overrides を使う
一時しのぎとして --legacy-peer-deps を使う場合は、恒久対応ではないと理解して使う

--legacy-peer-deps は古い解決方式に寄せるため、その場では入っても、将来の更新や CI で別の不整合を残しやすいです。常用より、原因調査の切り分け用と考えたほうが安全です。

2. `package-lock.json` と実際の状態がズレている

package-lock.json は、どの依存ツリーを入れたかを固定するためのファイルです。npm 公式も、チーム開発や CI で同じ依存構成を再現するためにコミットする前提のファイルとして説明しています。

ここが崩れる場面は多いです。

package.json だけ編集して package-lock.json を更新していない
別メンバーが違う npm 版でロックファイルを更新した
node_modules を手で触った
ブランチ切り替え後に古い node_modules を残した

この場合は、まずクリーンにそろえます。

rm -rf node_modules
npm install

CI や検証環境では、より再現性の高いこちらが向いています。

npm ci

npm ci は既存の package-lock.json を前提に、package.json と一致しなければエラーにします。つまり、ローカルでは気づきにくいロックファイルの不整合を早めにあぶり出せます。

3. Node.js / npm のバージョン差

依存関係そのものではなく、実行環境の差で失敗するケースです。package.json には engines を書けるため、パッケージ側が対応 Node.js / npm の範囲を指定していることがあります。

たとえば次のような指定です。

{
  "engines": {
    "node": ">=20 <25",
    "npm": ">=10"
  }
}

この条件に合わない環境では、警告や失敗の原因になります。特に古い Node.js で新しい依存を入れようとした場合、npm install の途中で別のエラーに見えることもあります。

対処は単純です。

Node.js をプロジェクト推奨版に合わせる
npm だけ更新してよいか確認する
チームでは .nvmrc や README で版を固定する

まずこの順で確認する基本手順

迷ったら、次の順番で見ていくと切り分けしやすいです。

手順1. エラーコードを拾う

ターミナルの最後だけでなく、少し上まで見てください。注目したい文字列は次です。

ERESOLVE
EACCES
ETARGET
ENOENT
ECONNRESET
404 Not Found
Unsupported engine

意味の目安はこうです。

ERESOLVE: 依存関係の解決失敗。まず依存の競合を見る
ETARGET: 指定したバージョンが存在しない。タイプミスや unpublished を疑う
Unsupported engine: Node.js / npm の条件に合っていない
ECONNRESET や 404: registry、ネットワーク、認証設定の可能性がある

手順2. 依存のつながりを確認する

競合パッケージ名が見えているなら、どこから入ってきたかを追います。

npm explain react
npm ls react --all

npm explain は、そのパッケージがなぜ入っているかを依存チェーンで見せるため、衝突元を特定しやすいです。

手順3. ロックファイルと `node_modules` を整理する

依存定義は正しいのに、手元だけ壊れていることがあります。そういうときはクリーンインストールです。

rm -rf node_modules
npm ci

npm ci が失敗したら、ロックファイルか package.json の整合性に問題がある可能性が高いです。ローカル開発なら、その後に npm install を実行してロックファイルの差分を確認します。

手順4. キャッシュや registry を確認する

毎回同じ場所で落ちる、ダウンロード周りで壊れるなら、キャッシュや registry 設定を見ます。

npm cache verify
npm config get registry
npm doctor

npm 公式では、キャッシュは自己修復的なので、いきなり全削除するより npm cache verify を先に行う流れが基本です。npm doctor は Node.js、git、registry、権限、キャッシュ整合性まで一通り診断できます。

よくあるエラー別の対処法

`ERESOLVE unable to resolve dependency tree`

最重要の確認対象です。 npm v7 以降で増えた代表例で、ほとんどは peerDependencies の競合です。

対処は次の順が安全です。

エラーログに出たパッケージ名と要求バージョンを読む
競合する主パッケージを対応版へ上げ下げする
依存元を npm explain で確認する
必要なら overrides で特定依存の版を固定する
応急処置として npm install --legacy-peer-deps を試し、通るなら競合が本丸だと判断する

overrides の例です。

{
  "overrides": {
    "some-shared-lib": "2.4.1"
  }
}

これは便利ですが、根本の互換性問題まで解決するわけではありません。テストが通るか確認してから採用してください。

`ETARGET No matching version found`

指定バージョン自体が registry に存在しないケースです。

ありがちな原因は次です。

バージョン番号のタイプミス
すでに削除・非推奨化された版を指定している
private registry 側にその版がない

まず package.json の指定を見直し、必要なら npm view <package名> versions で利用可能版を確認します。

`Unsupported engine`

Node.js や npm の版が条件外です。依存パッケージが新しい Node.js を要求しているのに、古い実行環境のまま入れようとすると起きます。

このエラーで重要なのは、依存をいじる前にランタイムをそろえること です。Node.js を LTS に上げるだけで解消することもあります。

ダウンロード系エラーや registry 関連

ECONNRESET、401、403、404 が出るなら、依存の中身より通信設定を疑います。

確認項目は次です。

npm config get registry が想定どおりか
社内 registry を使うなら認証が切れていないか
プロキシ環境で HTTPS 通信がブロックされていないか
.npmrc に古い設定が残っていないか

実務で使いやすい最小チェックリスト

作業前に、次の順で見るだけでもかなり違います。

node -v と npm -v を控える
エラーコードを 1 つ拾う
package.json と package-lock.json の差分を確認する
npm explain <package名> で依存元を追う
npm ci で再現するか確認する
registry と .npmrc を確認する
最後にだけキャッシュや node_modules の再作成を行う

NG対応と改善例

場当たり的に直すより、再現しやすい手順に置き換えたほうが後で困りません。

NG例

エラー本文を読まずに毎回 npm cache clean --force
毎回 --legacy-peer-deps を付ける
package-lock.json を理由なく削除してコミットする
ローカルでは通るからといって CI を見ない

改善例

まずエラーコードと競合パッケージ名を確認する
ロックファイルをコミットし、CI は npm ci に寄せる
バージョン差があるチームでは Node.js を固定する
一時回避を入れたら、後で overrides や依存更新で整理する

`npm install` と `npm ci` の使い分け

似ていますが、目的は少し違います。

コマンド	向いている場面	注意点
`npm install`	ローカル開発で依存追加や更新を行うとき	状況によって `package-lock.json` が更新される
`npm ci`	CI、検証環境、本番ビルドで同じ依存を再現したいとき	ロックファイルと `package.json` がズレていると失敗する

ローカルで依存を調整し、確定した状態を package-lock.json に残し、その再現には npm ci を使う。この流れがもっとも安定します。

それでも直らないときの見どころ

最後に、見落としやすい点を短くまとめます。

ネイティブモジュールが入るプロジェクトでは、Python、C/C++ ビルドツール、OS 差分でも失敗する
Git URL の依存があると、git が PATH にないだけで落ちることがある
ワークスペース構成では、ルートと各 workspace の依存関係を分けて見る必要がある
install-links や legacy-peer-deps 付きで作ったロックファイルは、CI 側でも同じ条件が必要になることがある

依存関係エラーは、1 回直して終わりではありません。チーム全体で Node.js / npm の版とロックファイル運用をそろえること が、次回の npm install 失敗を減らすいちばん現実的な対策です。次に見るべきなのは、あなたのプロジェクトで npm ci が毎回安定して通るかどうかです。

参照リンク

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！