Mac の npm キャッシュを安全に削除する方法
AskClean チーム · 更新日 2026-08-05
npm config get cache で使用中のキャッシュを特定し、そのパスを du で測ってから npm cache verify を実行してください。容量を今すぐ空ける必要があり、次回以降の再ダウンロードを受け入れられる場合だけ npm cache clean --force を使います。この操作は node_modules、package.json、lockfile を削除しません。
npm キャッシュと node_modules を分ける
npm のキャッシュは複数プロジェクトで再利用するダウンロードデータで、macOS の既定は ~/.npm ですが設定で変更できます。node_modules は各プロジェクトのインストール済み依存ツリーです。package.json と package-lock.json もキャッシュではなく再現可能な依存解決の入力です。旧 npm-shrinkwrap.json もプロジェクトファイルですが、npm v12 は読まないため、現在の npm で再インストールする前に package-lock.json へ改名します。
使用中のキャッシュを測定して検証する
~/.npm が存在するだけで使用中とは限りません。npm config get cache が返した正確なパスを測り、npm cache verify でインデックスと内容の整合性を検証し、不要データを回収します。npm のキャッシュは自己修復を前提としているため、通常の保守や多くのインストール障害では verify だけで十分です。ERESOLVE、認証、404、プロキシ、Node.js のエンジン要件、ネイティブビルド、postinstall スクリプトの問題は、有効なキャッシュを消しても直りません。
- npm --version と npm config get cache を実行し、表示されたパスがプロジェクトではなくキャッシュであることを確認します。
- 表示された正確なパスを du -sh で測り、macOS の空き容量も記録します。
- 実行中の npm install、npm ci、npm exec、publish を止めてから npm cache verify を実行し、結果とエラーを保存します。
- verify 後も回収が必要で、再ダウンロードできると確認した場合だけ npm cache clean --force を実行します。
- npm cache verify と測定をもう一度行い、元の lockfile のまま代表的なプロジェクトをインストール・ビルド・テストします。
未確認のパスを rm -rf に渡さないでください。この手順に手動の再帰削除は不要です。また、キャッシュ消去と lockfile の削除を同時に行うと、障害原因を比較できなくなります。
必要な場合だけ --force で消去する
測定したキャッシュが大きく、容量回収の価値が再利用価値を上回ると判断したときだけ npm cache clean --force を実行します。このコマンドは設定済みキャッシュを消去し、次回の install や npm ci でネットワークから再取得させます。プライベートレジストリ、Git ホスト、プロキシ、オフライン環境で必要なパッケージが利用できなければ、復旧は失敗します。force を永続設定にせず、このコマンドだけに付けてください。
依存グラフを変えずに結果を確かめる
キャッシュ削除後は npm config get cache と du で同じ場所を再測定し、元の package.json と lockfile を変更せず、代表的なプロジェクトを通常の手順でインストール・ビルド・テストします。同じエラーが戻るなら削除を繰り返さず、保存したエラーと npm・Node.js のバージョン、レジストリ設定を診断してください。AskClean が扱う npm 項目は既定の ~/.npm 全体で、設定変更済みのキャッシュは npm 自身で確認する必要があります。
削除判断と復旧コスト
npm が実際に使うダウンロードキャッシュを確認・測定し、まず整合性を検証して、必要な場合だけ消去します。node_modules とプロジェクトファイルは残します。
| 項目・操作 | 確認する場所 | 削除・操作後の結果 |
|---|---|---|
| npm キャッシュと node_modules を分ける | npm config get cache | npm のキャッシュは複数プロジェクトで再利用するダウンロードデータで、macOS の既定は ~/.npm ですが設定で変更できます。node_modules は各プロジェクトのインストール済み依存ツリーです。package.json と package-lock.json もキャッシュではなく再現可能な依存解決の入力です。旧 npm-shrinkwrap.json もプロジェクトファイルですが、npm v12 は読まないため、現在の npm で再インストールする前に package-lock.json へ改名します。 |
| 使用中のキャッシュを測定して検証する | npm cache verify | ~/.npm が存在するだけで使用中とは限りません。npm config get cache が返した正確なパスを測り、npm cache verify でインデックスと内容の整合性を検証し、不要データを回収します。npm のキャッシュは自己修復を前提としているため、通常の保守や多くのインストール障害では verify だけで十分です。ERESOLVE、認証、404、プロキシ、Node.js のエンジン要件、ネイティブビルド、postinstall スクリプトの問題は、有効なキャッシュを消しても直りません。 |
| 必要な場合だけ --force で消去する | npm cache clean --force | 測定したキャッシュが大きく、容量回収の価値が再利用価値を上回ると判断したときだけ npm cache clean --force を実行します。このコマンドは設定済みキャッシュを消去し、次回の install や npm ci でネットワークから再取得させます。プライベートレジストリ、Git ホスト、プロキシ、オフライン環境で必要なパッケージが利用できなければ、復旧は失敗します。force を永続設定にせず、このコマンドだけに付けてください。 |
| 依存グラフを変えずに結果を確かめる | インストール + オフライン/プライベートレジストリ確認 | キャッシュ削除後は npm config get cache と du で同じ場所を再測定し、元の package.json と lockfile を変更せず、代表的なプロジェクトを通常の手順でインストール・ビルド・テストします。同じエラーが戻るなら削除を繰り返さず、保存したエラーと npm・Node.js のバージョン、レジストリ設定を診断してください。AskClean が扱う npm 項目は既定の ~/.npm 全体で、設定変更済みのキャッシュは npm 自身で確認する必要があります。 |
よくある質問
npm cache clean --force は安全ですか？
正しい設定済みキャッシュを対象にすればプロジェクトのソースは消えませんが、再利用できるダウンロードを失います。先に測定と verify を行い、次回のネットワーク取得を受け入れられる場合だけ実行してください。
npm cache verify と clean のどちらを先に使いますか？
npm cache verify が先です。整合性を確認し、不要データだけを回収しながら有効な内容を残します。clean --force は、測定済みの容量回収または verify で直らないキャッシュ固有の問題に限定します。
npm キャッシュを消すと package-lock.json も消えますか？
消えません。package.json と package-lock.json はプロジェクトファイルです。npm v12 が読まない古い npm-shrinkwrap.json は package-lock.json へ改名しますが、キャッシュ削除の際に依存解決を書き換えてはいけません。
参考資料