Gradleのキャッシュ削除とクリーンビルドの正しい方法を解説

Gradleのキャッシュには種類がある？場所と役割を整理

Gradleのキャッシュは「グローバルキャッシュ」「プロジェクト固有キャッシュ」「ビルド出力」の3種類に分かれます。それぞれ保存場所と役割が異なるため、削除対象を間違えると不要な再ダウンロードや再コンパイルが発生します。

グローバルキャッシュ（Gradle User Home）の場所と役割

グローバルキャッシュはデフォルトで~/.gradle（WindowsならC:\Users\<ユーザー名>\.gradle）に保存されます。環境変数GRADLE_USER_HOMEで場所を変更できます。ここにはダウンロードした依存ライブラリやGradle配布物など、複数プロジェクトで共有されるデータが格納されます。

主なディレクトリと役割は次のとおりです。

• caches/modules-2/：ダウンロードした依存ライブラリ（JAR、POM）
• caches/build-cache-1/：ビルドキャッシュ（タスク出力の再利用データ）
• wrapper/dists/：Gradle WrapperがダウンロードしたGradle本体
• daemon/：Gradle Daemonのレジストリ・ログ
• jdks/：Java Toolchainで自動ダウンロードされたJDK

なお、daemon/ディレクトリは実行中のプロセス情報やログを保存するものであり、キャッシュではありません。init.d/やgradle.propertiesは設定ファイルのため、キャッシュ削除時に消すべきではありません。

要点：グローバルキャッシュは~/.gradleにあり、依存ライブラリやGradle本体など複数プロジェクトで共有されるデータが保存される

プロジェクト固有キャッシュ（.gradle）とビルド出力（build/）の違い

プロジェクトルート直下の.gradle/ディレクトリには増分ビルド用のタスク情報が保存されます。Gradleはこの情報を使って前回のビルドから変更された部分だけを再実行します。このディレクトリは一時生成物であり、ソース管理にはコミットすべきではありません。

一方、build/ディレクトリはコンパイル済みクラス、JAR、テスト結果、レポートなどのビルド成果物を格納します。cleanタスクで削除されるのはこのbuild/ディレクトリだけです。

両者の違いを整理すると次のとおりです。

要点：.gradle/は増分ビルド用のタスク情報、build/はビルド成果物。cleanで削除されるのはbuild/のみ

キャッシュの自動クリーンアップ機能

Gradleはデフォルトで24時間ごとにグローバルキャッシュを自動クリーンアップします。これはGradle Daemonの停止時やシャットダウン時にバックグラウンドで実行されます。--no-daemon利用時はビルドセッション後に実行されます。

自動クリーンアップの保持期間は次のとおりです。未使用のキャッシュがこの期間を過ぎると自動的に削除されます。

保持期間は~/.gradle/init.d/配下のinitスクリプトで変更できます。手動で頻繁にrm -rfする必要はないことを覚えておきましょう。

要点：Gradleは未使用キャッシュを24時間ごとに自動削除する。手動削除は必要な場合のみで十分

Gradleのcleanタスクで削除できるもの・できないもの

cleanタスクはビルド出力（build/ディレクトリ）だけを削除するタスクです。グローバルキャッシュやプロジェクト固有キャッシュは削除しません。この違いを理解していないと、キャッシュを消したつもりが残ったままになり、問題が解決しないことがあります。

cleanタスクの基本的な動作

cleanタスクはBase Pluginが提供するDelete型タスクです。JavaプロジェクトではJava Pluginを適用すると自動的に利用できます。実行するとlayout.buildDirectoryで指定されたディレクトリ、つまりデフォルトのbuild/ディレクトリを丸ごと削除します。

基本的な実行コマンドは次のとおりです。

1. プロジェクトルートで./gradlew cleanを実行する
2. build/ディレクトリが削除される
3. 次回のビルドですべてのソースが再コンパイルされる

マルチプロジェクト構成では./gradlew :モジュール名:cleanと指定することで、特定モジュールのビルド出力だけを削除できます。

要点：cleanタスクはbuild/ディレクトリだけを削除する。依存ライブラリやビルドキャッシュは削除されない

cleanタスクで削除できないもの

削除できないのは、グローバルキャッシュとプロジェクト固有キャッシュです。具体的には、ダウンロード済みの依存ライブラリ（~/.gradle/caches/modules-2/）、ビルドキャッシュ（~/.gradle/caches/build-cache-1/）、増分ビルド情報（.gradle/）などが残ります。

依存関係の不整合を解消したい場合、cleanだけでは不十分です。依存ライブラリのキャッシュを削除するか、--refresh-dependenciesオプションでリモートリポジトリを再確認する必要があります。

--refresh-dependenciesはキャッシュを削除せずに依存の鮮度を更新できる便利なオプションですが、全依存を毎回再確認するため低速です。恒常的な対策ではなく一時的な対策として使用してください。

要点：依存関係の問題を解決するにはcleanだけでなく、依存キャッシュの削除または--refresh-dependenciesが必要

cleanタスク使用時の注意点

cleanを実行すると増分ビルド情報が失われ、次回ビルドはフルコンパイルになります。プロジェクトの規模によってはビルド時間が大幅に増えることがあります。そのため、cleanは必要なときだけ実行するのが効率的です。

また、JavaプラグインではcleanJarやcleanTestのように、タスク名にcleanを付けた形式で個別タスクの出力だけを削除することもできます。全体をクリーンする必要がない場合は、この方法で部分的に削除できます。

よくある誤解として「cleanで全キャッシュが削除される」というものがありますが、実際にはビルド出力のみが対象です。キャッシュを完全に消したい場合は、後述の手動削除が必要です。

要点：clean後はフルコンパイルになるため必要なときだけ実行する。個別タスクの出力のみ削除するcleanタスク名も利用可能

Gradleのビルドキャッシュを無効化・削除する方法

ビルドキャッシュはタスクの出力を再利用してビルド時間を短縮する仕組みです。タスクの入力が同じであれば、出力をキャッシュから取得してタスク実行をスキップできます。ただし、デフォルトでは無効のため、利用するには明示的な有効化が必要です。

ビルドキャッシュの仕組みと有効化方法

ビルドキャッシュが有効な状態でタスクがキャッシュから復元されると、ビルドログにFROM-CACHEと表示されます。これにより、コンパイルやテストなどの実行時間を大幅に削減できます。

有効化する方法は次のとおりです。

1. コマンドラインで一時的に有効化：./gradlew build --build-cache
2. プロジェクト全体で有効化：gradle.propertiesにorg.gradle.caching=trueを追記
3. 無効化したい場合：--no-build-cacheオプションを使用

キャッシュ可能なタスクにはJavaCompile、Test、Javadocなどがあります。一方、CopyやJarなどはデフォルトでキャッシュ対象外です。カスタムタスクをキャッシュ対応にするには@CacheableTaskアノテーションが必要です。

要点：ビルドキャッシュはデフォルト無効。--build-cacheまたはorg.gradle.caching=trueで有効化する

ビルドキャッシュの保存場所と削除方法

ビルドキャッシュのデフォルト保存場所は~/.gradle/caches/build-cache-1/です。Gradle 8以降、ビルドキャッシュを削除する専用タスクとしてcleanBuildCacheタスクが削除されたため、ディレクトリを直接削除する必要があります。

削除手順は次のとおりです。

1. Gradle Daemonを停止する（./gradlew --stop）
2. rm -rf ~/.gradle/caches/build-cache-1/を実行する
3. 必要に応じて再度ビルドする

Windowsで削除が失敗する場合、Gradle Daemonがファイルをロックしている可能性があります。必ず--stopでDaemonを停止してから削除してください。settings.gradleのbuildCache { local { directory = ... } }で保存場所を変更することもできます。

要点：ビルドキャッシュは~/.gradle/caches/build-cache-1/にあり、Daemon停止後に直接削除する。Gradle 8以降cleanBuildCacheタスクは使えない

cleanとビルドキャッシュを組み合わせた高速化

cleanを実行してもビルドキャッシュは残るため、クリーンビルドと高速化を両立できます。具体的には、clean後に--build-cacheを付けてビルドすると、キャッシュ済みタスクはFROM-CACHEとして実行をスキップします。

実行コマンドの例は次のとおりです。

./gradlew clean build --build-cache

CI環境では「クリーンビルドでリモートキャッシュを更新し、開発者はリモートキャッシュから取得する」という構成が推奨されています。ビルドキャッシュを活用することで、cleanによるフルコンパイルのデメリットを軽減できます。

要点：cleanと--build-cacheを組み合わせると、クリーンな状態でもキャッシュから復元でき高速化できる

Gradleのキャッシュ削除をIDE（VSCode・Eclipse・IntelliJ）で行う手順

IDEからGradleのキャッシュを削除する場合、基本的にはGradleタスクの実行と手動削除の組み合わせになります。IDEによってGradleとの連携方法が異なるため、それぞれの手順を確認しておきましょう。

IntelliJ IDEAでのキャッシュ削除手順

IntelliJ IDEAはGradleとの連携が強力で、Gradleツールウィンドウから直接タスクを実行できます。cleanタスクを実行するには、右側のGradleタブを開き、プロジェクト名 > Tasks > build > cleanをダブルクリックします。

ビルドキャッシュを有効にして実行したい場合は、次の手順で設定できます。

1. Settings（Ctrl+Alt+S / Cmd+,）を開く
2. Build, Execution, Deployment > Build Tools > Gradle を選択
3. 「Build and run using」でGradleを選択していることを確認する
4. 必要に応じて「Build and run」のオプションに--build-cacheを追加する

グローバルキャッシュの削除はIDEから直接実行できないため、ターミナルでrm -rf ~/.gradle/caches/などを実行する必要があります。IntelliJ内蔵ターミナルから実行しても問題ありません。

要点：IntelliJ IDEAではGradleツールウィンドウからcleanタスクを実行できる。グローバルキャッシュ削除はターミナルで手動実行

Eclipseでのキャッシュ削除手順

EclipseでGradleプロジェクトを扱う場合、Buildshipプラグインを使用します。BuildshipではGradle Tasksビューからcleanタスクを実行できます。Gradle Tasksビューを開き、プロジェクト > build > cleanを右クリックして「Run Gradle Tasks」を選択します。

ビルドキャッシュを有効にしたビルドを実行するには、次の手順で引数を追加します。

1. プロジェクトを右クリックして「Run As」>「Gradle Build…」を選択
2. 「Arguments」タブでProgram Argumentsにclean build --build-cacheを入力
3. 「Run」をクリックして実行

グローバルキャッシュの手動削除は、Eclipseのコンソールや外部ターミナルからrm -rf ~/.gradle/caches/などを実行します。削除前に./gradlew --stopでDaemonを停止することを忘れないでください。

要点：EclipseではBuildshipのGradle Tasksビューからcleanを実行し、引数に--build-cacheを追加できる

VSCodeでのキャッシュ削除手順

VSCodeにはGradle専用の公式拡張機能はありませんが、「Gradle for Java」拡張機能を使用するとGradleプロジェクトを管理できます。この拡張機能では、Gradle Projectsビューからタスクを実行できます。

手順は次のとおりです。

1. Extensions（Ctrl+Shift+X / Cmd+Shift+X）で「Gradle for Java」をインストール
2. サイドバーのGradleアイコンをクリックしてGradle Projectsビューを開く
3. プロジェクト > build > clean をクリックして実行

VSCodeで--build-cacheを付けて実行したい場合は、ターミナルから./gradlew clean build --build-cacheを直接実行するのが最も確実です。VSCodeの統合ターミナル（Ctrl+`）から実行できます。グローバルキャッシュの削除も同様にターミナルから行います。

要点：VSCodeではGradle for Java拡張機能でcleanタスクを実行し、--build-cache付きのビルドはターミナルから直接実行するのが確実

Gradleキャッシュ削除の注意点とビルドを高速化するコツ

キャッシュ削除は「必要なキャッシュだけを、必要なときに削除する」ことが基本です。削除すればするほどビルドは遅くなります。問題が発生したときに原因に応じたキャッシュを特定して削除するのが効率的です。

キャッシュ削除時の重要な注意点

rm -rf ~/.gradle全体の削除は非推奨です。gradle.propertiesやinit.d/の設定ファイル、ダウンロード済みのWrapper配布物まで消えてしまい、不要な再ダウンロードと再設定が必要になります。削除するのは問題が発生しているcaches/配下の特定ディレクトリに限定しましょう。

ケース別の削除コマンドを整理します。

削除前に./gradlew --stopでGradle Daemonを停止することを忘れないでください。Windowsではファイルロックにより削除が失敗する原因になります。

要点：~/.gradle全体の削除は避け、問題に応じたキャッシュだけを削除する。削除前にはDaemonを停止する

ビルドを高速化するための設定

Gradleのビルドを高速化するには、キャッシュを消すのではなく活用することが重要です。ビルドキャッシュを有効化（org.gradle.caching=true）することで、同じ入力のタスクはキャッシュから復元され、実行時間を短縮できます。

また、キャッシュクリーンアップの保持期間を延長することで、キャッシュ再利用の機会を増やせます。~/.gradle/init.d/配下のinitスクリプトで次のように設定します。

// ~/.gradle/init.d/cache-settings.gradle
beforeSettings { settings ->
    settings.caches {
        downloadedResources.removeUnusedEntriesAfterDays = 45
        createdResources.removeUnusedEntriesAfterDays = 10
    }
}

頻繁にcleanを実行する習慣がある場合は見直しましょう。cleanは増分ビルドのメリットを失わせるため、必要なときだけ実行するのが基本です。

要点：ビルドキャッシュの有効化とキャッシュ保持期間の延長でビルドを高速化できる。cleanの多用は避ける

トラブルシューティングと対処法

キャッシュが原因でビルドに問題が発生した場合、原因に応じた対処を選ぶことが重要です。依存関係の不整合なら依存キャッシュの削除、タスク出力の不整合ならビルドキャッシュの削除、増分ビルドの誤動作ならプロジェクト固有キャッシュの削除を検討します。

SNAPSHOT依存の更新を反映したい場合、キャッシュを削除せずに--refresh-dependenciesを使う方法もあります。ただし全依存を再確認するため低速であり、一時的な対策として使用してください。

CI環境ではキャッシュ復元設定も確認しましょう。ローカルのキャッシュを削除しても、CIのキャッシュ設定が残っていれば復元されることがあります。キャッシュを完全にリセットしたい場合は、CI側のキャッシュ設定も合わせて確認する必要があります。

どうしても問題が解決しない場合の最終手段としてrm -rf ~/.gradle/caches/で全キャッシュを削除できますが、次回ビルドで依存ライブラリの再ダウンロードに時間がかかることを覚悟してください。

要点：問題の原因に応じたキャッシュを特定して削除する。全キャッシュ削除は最終手段として、再ダウンロードのコストを理解して実行する

“`