npm installが失敗する時の原因と対処法｜エラー別にやさしく解説

プロジェクトを動かそうとして「npm install」を実行したら、赤いエラーがずらり——。

環境構築の入り口で、いきなりつまずいてしまう人はとても多いです。

ですが、npm installの失敗は原因のパターンがある程度決まっているため、順番に対処すればたいてい解決できます。

この記事では、npm installが失敗する原因と対処法を、初心者にもわかりやすく解説します。

この記事の対象読者

• npm installがエラーで止まってしまう方
• 環境構築でつまずいている初心者の方
• エラーの原因を切り分けて直したい方
• とりあえず何から試せばいいか知りたい方

まず試したい基本の対処

原因が特定できないときは、いったんキャッシュと生成物を消して、入れ直すのが定番です。

# キャッシュを消す
npm cache clean --force

# node_modules と lock ファイルを消して入れ直す
rm -rf node_modules package-lock.json
npm install

# キャッシュを消す
npm cache clean --force

# node_modules と lock ファイルを消して入れ直す
rm -rf node_modules package-lock.json
npm install

これだけで直るケースも多いので、まずはここから試してみましょう。

エラー別の対処法

①ネットワーク系のエラー（network / ETIMEDOUT）

ダウンロード先に接続できずに失敗するパターンです。

ネット接続を確認し、社内ネットワークなどではプロキシ設定が必要なこともあります。

VPNやセキュリティソフトが通信を遮っていないかも、あわせて確認しましょう。

②権限エラー（EACCES / permission denied）

ファイルへの書き込み権限がなくて失敗するパターンです。

ここで安易にsudoで無理やり通すのは避けましょう。あとで別の不具合の原因になりがちです。

おすすめは、nvmなどのバージョン管理ツールでNode.jsを入れ直し、権限で困らない形にすることです。

③依存関係の衝突（ERESOLVE / peer deps）

パッケージ同士が要求するバージョンが噛み合わず、止まるパターンです。

まずはエラー文を読み、どのパッケージが衝突しているかを確認します。

一時的な回避としては、次のオプションが使われることもあります（乱用は禁物です）。

# 依存の食い違いを許容してインストールする（応急処置）
npm install --legacy-peer-deps

# 依存の食い違いを許容してインストールする（応急処置）
npm install --legacy-peer-deps

④Node.js・npmのバージョンが合わない

プロジェクトが求めるバージョンと、手元のバージョンがズレていると失敗します。

まずは、いま使っているバージョンを確認しましょう。

# Node.js と npm のバージョンを確認する
node -v
npm -v

# Node.js と npm のバージョンを確認する
node -v
npm -v

プロジェクトの指定（enginesや.nvmrcなど）に合わせて、Node.jsのバージョンをそろえると解決します。

それでもダメなときのチェック

ここまでで直らないときは、次の点を落ち着いて確認しましょう。

• エラー文の一番上を読む：本当の原因は最初のほうに書かれていることが多い
• node_modulesとlockを消して再取得：中途半端な状態をリセットする
• 別のネットワークで試す：通信環境が原因か切り分けられる

環境構築まわりのトラブルは、こちらの記事もあわせてどうぞ。

あわせて読みたい

localhostにつながらない時の原因と解決方法｜初心者向けにやさしく解説 ローカル環境で開発をしようとブラウザで「localhost」にアクセスしたら、「このサイトにアクセスできません」「localhost で接続が拒否されました」と表示されて、作業…

あわせて読みたい

ポートが使用中で起動できない時の対処法｜原因とプロセスの止め方をやさしく解説 開発サーバー起動時の「address already in use」エラーの原因と対処法を解説。別ポートでの起動から、使用中プロセスの見つけ方・止め方（Mac・Windows）まで、コマンド例つきで紹介します。

まとめ

npm installの失敗は、まずキャッシュとnode_modulesを消して入れ直すのが基本の第一手です。

それでも直らないときは、エラー文を読んで「ネットワーク」「権限」「依存」「バージョン」のどれかを見分けましょう。

原因の種類さえ分かれば、対処はぐっと近づきます。あわてず一つずつ進めていきましょう。

よくある質問

sudoで実行すれば直りますか？

その場は通っても、あとで権限がおかしくなり別の不具合を招くことがあります。基本はsudoに頼らず、nvmなどでNode.jsを管理して権限の問題を根本から避けるのがおすすめです。

package-lock.jsonは消してもいいですか？

通常はバージョンを固定する大切なファイルなので、むやみに消しません。ただし原因の切り分けとして、node_modulesとあわせて一度消して入れ直すのは有効な手です。

npm install と npm ci は何が違いますか？

npm ciはlockファイルの通りに厳密にインストールし直すコマンドで、クリーンな環境やCIでの再現に向いています。まっさらな状態から入れ直したいときに便利です。

–legacy-peer-deps は使って大丈夫ですか？

依存の食い違いを一時的に回避する応急処置です。動くようにはなりますが、根本原因が残ることもあるため、余裕があるときにバージョンの整理をしておくと安心です。

どのNode.jsのバージョンを使えばいいですか？

プロジェクトが指定しているバージョン（enginesや.nvmrcなど）に合わせるのが基本です。指定がなければ、安定版であるLTSを選んでおくと無難です。