npm cache cleanを使って、npmのキャッシュクリアをしたいけれど、「–forceを付けないと実行できないのはなぜ？」「キャッシュを削除してもnode_modulesは大丈夫？」と疑問に感じていませんか？
npmのキャッシュは通常、頻繁に削除する必要はありません。しかし、キャッシュの肥大化や破損が原因と思われるエラーが発生した場合は、正しい方法でクリアすることで問題の切り分けに役立ちます。また、OSによってキャッシュの保存場所や削除方法が異なるため、環境に合った手順を知っておくことも大切です。
この記事では、npm cache clean --forceを使ったキャッシュの削除方法から、npm cache verifyによる状態確認、Windows・Mac・Linuxでの保存場所と削除方法まで詳しく解説します。さらに、キャッシュをクリアしてもエラーが直らない場合の対処法も紹介します。
npmキャッシュをクリアする基本コマンドと正しい使い方
npm cache clean --forceでnpmキャッシュを削除する
npmキャッシュを削除する際は、以下のコマンドを実行します。
npm cache clean --force実行すると、特にメッセージは表示されずコマンドプロンプトが戻ってくるだけです。裏側ではキャッシュフォルダ内のパッケージデータ（tarballや圧縮ファイルなど）が削除されています。実行後にnpm installを行うと、npmはローカルキャッシュを参照できないため、レジストリ（npmのサーバー）から改めてパッケージをダウンロードします。そのため、初回のインストール時間がいつもより長くなる点は事前に把握しておく必要があります。なお、キャッシュ削除だけではnode_modulesフォルダの中身やインストール済みパッケージのバージョンは変わりません。あくまで「次回ダウンロード時の参照元」をリセットする操作です。
「–force」オプションなしで削除できない理由と公式の仕様
npm cache cleanだけを実行すると、以下のようなエラーが返ってきます。
npm ERR! As of npm@5, the npm cache self-heals from corruption issues and data extracted from the cache is guaranteed to be valid. If you want to make sure everything is consistent, use `npm cache verify` instead.
npm ERR! Note that this command is unnecessary in most situations and is potentially destructive when run against a corrupted cache. If you have reproducible steps, npm cache clean --force has been added to allow you to actually clean the cache.これは公式ドキュメント（npm-cache | npm Docs）にも明記されている通り、npm v5以降のキャッシュには整合性チェック機能が組み込まれており、通常の運用でキャッシュが壊れることはほぼ想定されていないためです。過去のバージョンでは「不具合が起きたらとりあえずキャッシュを消す」という対処法が広まった結果、必要のないキャッシュ削除が頻発し、逆にインストール速度の低下を招くケースが目立ちました。この経緯から、npm開発チームは意図的に--forceを必須とし、利用者に「本当に削除が必要か」を一度立ち止まって判断させる仕様に変更しています。
npm cache verifyでキャッシュの状態を確認する方法
キャッシュを全削除する前に、まず状態を確認したい場合は次のコマンドを使います。
npm cache verify実行すると、以下のような結果が表示されます。
Cache verified and compressed (~/.npm/_cacache)
Content verified: 1234 (56789012 bytes)
Index entries: 1456
Finished in 2.34sこのコマンドは、キャッシュ内のデータが破損していないかをチェックし、不要になった古いデータがあれば自動的に整理します。npmのキャッシュは前述の通り自己修復の仕組みを持っているため、多くの場合はエラーの原因がキャッシュではなく、node_modulesやネットワーク設定側にあります。したがって、いきなり--forceで全削除するよりも、先にnpm cache verifyを試して問題を切り分ける進め方のほうが、後工程の手間を減らせます。
【OS別】npmキャッシュの保存場所と削除方法（Windows・Mac・Linux）
npm config get cacheで保存場所を確認する方法
キャッシュを削除する前に、自分の環境でどこにキャッシュが保存されているかを確認しておくと安心です。OSを問わず、以下のコマンドで確認できます。
npm config get cacheMacやほとんどのlinux環境では、次のようなパスが表示されます。
/Users/ユーザー名/.npmWindowsの場合は、以下のようなパスになります。
C:\Users\ユーザー名\AppData\Roaming\npm-cacheこのパスは環境変数や.npmrcの設定によって変更されている場合もあるため、必ず表示された結果をそのまま確認するようにしてください。フォルダの中身を直接見てファイルを手動削除することも技術的には可能ですが、npmが管理しているインデックス情報との整合性が崩れる恐れがあるため、後述の専用コマンドを使う方法をおすすめします。
Windows（コマンドプロンプト・PowerShell）でのnpmのキャッシュクリア手順
Windows環境では、コマンドプロンプトとPowerShellのどちらからでも同じコマンドでキャッシュを削除できます。
npm cache clean --force通常のユーザー権限で実行すれば問題なく完了しますが、npmをグローバルインストールしたディレクトリの権限設定によっては、以下のような権限エラーが出ることがあります。
npm ERR! code EPERM
npm ERR! syscall rmdirこのエラーが出た場合は、コマンドプロンプトまたはPowerShellを「管理者として実行」から起動し直したうえで、同じコマンドを再実行してください。また、社内PCなどグループポリシーでアクセス権が制限されている環境では、情シス部門に確認したほうが早く解決するケースもあります。
Mac・Linuxでのnpmのキャッシュクリア手順と管理者権限の要否
Mac・Linuxのターミナルでも、コマンド自体はWindowsと共通です。
npm cache clean --force基本的には管理者権限（sudo）を付けずに実行して問題ありません。Node.jsをnvm（Node Version Manager）経由でインストールしている場合、キャッシュフォルダの所有者は自分のユーザーになっているため、そのままの権限で削除まで完了します。一方、Homebrew以外の方法でNode.jsをシステム全体にインストールした場合や、過去にsudo npm installを実行した履歴がある場合は、キャッシュフォルダの所有者がrootのままになっていることがあります。この状態で権限エラーが出た場合のみ、以下のようにsudoを付けて実行してください。
sudo npm cache clean --forceなお、sudoを常用する運用は今後の権限トラブルの原因になりやすいため、根本的にはnvmなどでNode.jsを個人権限で管理し直すことを検討する価値があります。
npmキャッシュクリアによる影響node_modulesや環境は安全？
キャッシュクリアで何が削除される？肥大化したディスク容量の確保
npm cache clean --forceで削除されるのは、~/.npm（WindowsではAppData\Roaming\npm-cache）配下に保存されている、過去にダウンロードしたパッケージのtarballファイルと、それに紐づくインデックス情報だけです。プロジェクトのソースコードや設定ファイルには一切触れません。長期間開発を続けているPCでは、このキャッシュフォルダが数GB単位に膨れ上がっていることも珍しくなく、削除前に容量を確認すると変化がわかりやすいです。
du -sh ~/.npm削除後に同じコマンドを実行すると、フォルダサイズが大幅に小さくなっているのが確認できます。ディスク容量が逼迫している場合の対処法として、この副次的な効果を目的にキャッシュクリアを行う開発者も少なくありません。
node_modulesやpackage-lock.jsonへの影響・変更の有無
結論から言うと、npm cache clean --forceを実行しても、プロジェクトフォルダ内のnode_modulesやpackage-lock.jsonは一切変更されません。キャッシュはあくまで「次にインストールする際の参照元」であり、すでにインストール済みのファイルやロックファイルに記録されたバージョン情報とは別管理になっています。実際に検証してみても、キャッシュクリアの前後でnode_modulesのフォルダ構成やファイルのタイムスタンプに変化は見られませんでした。「キャッシュを消したらインストール済みのパッケージも消えるのでは」という不安を持つ方もいますが、その心配は不要です。影響が及ぶのは、次回npm installを実行したタイミング以降のダウンロード処理のみです。
インストール済みパッケージやnpmの動作速度への影響
すでに動いているアプリケーションやビルド済みの成果物に対して、キャッシュクリアが直接的な悪影響を与えることはありません。ただし、次にnpm installやnpm ciを実行する際は、ローカルキャッシュを参照できない分、レジストリへのダウンロードが増え、通常より処理時間が長くなります。回線速度やパッケージ数によっては、体感で数倍の差が出ることもあります。日常的な開発フローの中で理由もなく毎回キャッシュクリアを挟むと、この速度低下だけが積み重なってしまうため、後述するようにエラーが実際に発生した場合の対処法として使う、という位置づけで扱うのが妥当です。
npmキャッシュクリアしてもエラーが直らないときの対処法
node_modulesを削除してnpm installをやり直す
npm cache clean --forceを実行してからnpm installをやり直してもエラーが変わらない場合、次に試すべきはnode_modulesフォルダの削除です。キャッシュが正常でも、既存のnode_modules内で依存関係が壊れていたり、途中でインストールが中断してファイルが不完全な状態になっていたりするケースは珍しくありません。
rm -rf node_modules
npm installWindowsでコマンドプロンプトを使っている場合は、以下のコマンドを使います。
rmdir /s /q node_modules
npm install再インストール後は、node_modules内のファイル数やサイズが以前と変わっているかを確認すると、正しく再構築されたかどうかの目安になります。この時点でエラーが解消するケースは実務上かなり多く、キャッシュクリアの次に試す対処法として優先度が高い手順です。
package-lock.jsonを削除する前に確認したいこと
node_modulesの削除でも直らない場合、package-lock.jsonの削除に進む開発者が多いのですが、これはチーム開発では慎重に判断すべき手順です。package-lock.jsonにはプロジェクト全体で固定している依存パッケージの正確なバージョンが記録されており、削除するとpackage.jsonのバージョン範囲指定（^や~など）に基づいて、npmが改めて最新の組み合わせを解決し直します。その結果、意図せず依存パッケージのマイナーバージョンが上がり、動作に差異が出る可能性があります。
rm package-lock.json
rm -rf node_modules
npm install削除する前には、Gitでコミット履歴を確認するか、一度ファイルをバックアップしておくことをおすすめします。もし削除後に別の不具合が出た場合、git checkout -- package-lock.jsonで元のロックファイルに戻せる状態を確保しておくと、後戻りしやすくなります。
Node.js・npmのバージョンやネットワークを確認する
ここまでの手順でも解決しない場合、原因がキャッシュや依存関係ではなく、実行環境側にあることを疑います。まずはバージョンを確認します。
node -v
npm -vプロジェクトが要求するNode.jsのバージョンと、実際にインストールされているバージョンがずれていないかをpackage.jsonのengines欄と照らし合わせてください。バージョン管理にはnvmを使うと切り替えが簡単です。
nvm install 18
nvm use 18また、社内ネットワークやVPN環境ではプロキシ設定が原因でパッケージのダウンロードに失敗することもあります。
npm config get proxy
npm config get https-proxy意図しないプロキシ設定が残っている場合は、npm config delete proxyで削除してから再度インストールを試してください。
よくある質問（FAQ）
-
npm cache cleanは危険なコマンドなのでしょうか？
-
正常な環境で実行する分には、危険な操作ではありません。削除されるのはダウンロード済みパッケージの一時データのみで、プロジェクトの
node_modulesやpackage-lock.jsonには影響しません。ただし、削除後の初回インストールで通信時間が伸びる点は把握しておいてください。npmが--forceを必須にしているのも、安易な多用を防ぐための仕様であり、コマンド自体に破壊的な副作用があるわけではありません。
-
キャッシュを自動で消す設定や、定期的にクリーンアップする方法はありますか？
-
npm自体には、キャッシュを定期的に自動削除する公式のスケジューリング機能はありません。
npm cache verifyを実行すると、古くなった不要データが自動的に整理される仕組みはありますが、完全な削除ではありません。定期的な自動クリーンアップを行いたい場合は、cronやタスクスケジューラにnpm cache clean --forceを登録する方法もありますが、前述の速度低下を考えると、常時稼働する開発マシンでは手動実行にとどめたほうが無難です。
-
yarnやpnpmを使っている場合も、同じ手順でキャッシュを削除できますか？ -
コマンド自体は異なります。yarnの場合は
yarn cache clean、pnpmの場合はpnpm store pruneを使います。いずれもキャッシュの保存場所や管理方式がnpmとは別になっているため、npmのキャッシュだけを削除してもyarnやpnpmのキャッシュには影響しません。プロジェクトによって使用しているパッケージマネージャーをpackage-lock.json・yarn.lock・pnpm-lock.yamlのいずれが存在するかで確認してから、対応するコマンドを選んでください。
-
npm cache clean --forceを実行した後、npm installが以前より遅くなりました。これは正常ですか？ -
正常な挙動です。キャッシュを削除した直後は、すべてのパッケージをレジストリから再ダウンロードするため、通常のインストールより時間がかかります。2回目以降の
npm installでは、新たに作られたキャッシュが再び使われるため、速度は元に戻ります。毎回極端に遅い状態が続く場合は、キャッシュではなくネットワーク環境やプロキシ設定側の問題を疑ってください。
-
npm ciを使っている場合も、キャッシュクリアは有効ですか？ -
有効です。
npm ciはpackage-lock.jsonの内容に厳密に従ってインストールを行うコマンドですが、パッケージの取得元としてローカルキャッシュを参照する点はnpm installと同じです。キャッシュ由来のエラーが疑われる場合は、npm cache clean --forceを実行してからnpm ciを再実行する対処法が使えます。ただしnpm ciは実行時にnode_modulesを自動的に削除してから再構築する仕様のため、事前に手動でnode_modulesを消しておく必要はありません。
まとめ
npmキャッシュのクリアは、正しい手順を踏めばプロジェクトの環境を壊す心配のない、比較的安全な操作です。この記事で解説した内容を振り返ります。
今すぐ何かひとつ実行するなら、まず次のコマンドから試してください。
npm cache verifyこれで異常が見つからず、それでもエラーが解消しない場合に、次のコマンドで本格的にキャッシュをクリアします。
npm cache clean --forceそれでも症状が変わらない場合は、この記事の「エラーが直らないときの対処法」のセクションに沿って、node_modulesの再構築から順に進めてください。
