概要: Gradleプロジェクトで依存関係を更新するリフレッシュ方法と、ビルド時に発生するメモリ不足エラーの対処法を解説します。IDEでの再読み込みとコマンドラインでの–refresh-dependenciesの違い、gradle.propertiesによるメモリ設定の手順を紹介します。
Gradleのリフレッシュとは？IDEとコマンドラインでの種類と違い
Gradleのリフレッシュには2つの種類がある
Gradleの「リフレッシュ」と呼ばれる操作には、大きく分けて2つの種類があります。1つはIDE（IntelliJ IDEAなど）でGradleプロジェクトを再読み込みする操作、もう1つはコマンドラインで依存関係のキャッシュを強制的に更新する--refresh-dependenciesです。両者は目的も動作も異なるため、混同しないことが重要です。
IDEでの再読み込みは、ビルド設定ファイルの変更をIDEに反映させるための操作です。一方、--refresh-dependenciesはリモートリポジトリに更新版がないかを確認し、変更が検出された場合のみダウンロードを行います。この操作は必要時のみ実行することが推奨されます。
IDEでの再読み込みと依存関係リフレッシュの違い
IntelliJ IDEAでは、Gradleツールウィンドウのリロードアイコン（象のアイコン）をクリックすることでプロジェクトの再読み込みができます。この操作は単にビルド設定をIDEに反映させるもので、依存関係のキャッシュ更新までは行いません。
一方、同じツールウィンドウの「Reload All Gradle Projects」は--refresh-dependencies相当の依存関係リフレッシュを実行します。つまり、IDE内でも操作の種類によって挙動が異なるのです。確実に依存関係を更新したい場合は、コマンドラインで./gradlew --refresh-dependenciesを実行する方法が明確です。
リフレッシュを使い分ける判断基準
状況によって適切なリフレッシュ方法は異なります。
- build.gradleなどの設定ファイルを変更した直後：IDEの再読み込みで十分です。
- ライブラリの新しいバージョンがリポジトリに公開された場合：
--refresh-dependenciesを使用します。 - 依存関係の解決がうまくいかない、キャッシュが疑われる場合：
--refresh-dependenciesを試します。 - 通常のビルド実行前：リフレッシュは不要です。毎回実行するとビルドが遅くなります。
要点：IDEの再読み込みは設定反映、--refresh-dependenciesは依存関係キャッシュの更新。通常のビルドでは毎回のリフレッシュは不要です。
コマンドラインで依存関係をリフレッシュする方法
–refresh-dependenciesの基本的な使い方
コマンドラインで依存関係をリフレッシュするには、プロジェクトのルートディレクトリで以下のコマンドを実行します。
- Windowsの場合：
gradlew.bat --refresh-dependencies - macOS/Linuxの場合：
./gradlew --refresh-dependencies
このコマンドはキャッシュを迂回し、リモートリポジトリに更新版がないかをチェックします。変更が検出された場合のみダウンロードを行い、ハッシュ値によって不要なダウンロードを回避するため、必要以上に時間はかかりません。
特定のタスクと組み合わせて実行する
--refresh-dependenciesは、他のGradleタスクと組み合わせて実行できます。例えば、依存関係をリフレッシュしてからビルドを実行するには以下のように指定します。
./gradlew build --refresh-dependencies
この方法を使えば、一度のコマンド実行で依存関係の更新確認とビルドを連続して行えます。また、cleanタスクと組み合わせて./gradlew clean build --refresh-dependenciesのように実行することも可能です。
リフレッシュを実行する際の注意点
--refresh-dependenciesは全依存関係を対象に更新確認を行うため、通常のビルドより時間がかかります。毎回のビルドで実行するのではなく、依存関係に問題が発生した場合や、新しいバージョンが公開されたことを確認したい場合に限定して使用してください。
また、この操作は依存関係のキャッシュを更新するだけで、Gradleデーモンの設定やメモリ設定には影響しません。メモリ不足エラーが発生している場合は、別途gradle.propertiesでの設定変更が必要です。
IntelliJ IDEAでGradleプロジェクトを再読み込み・リフレッシュする方法
Gradleツールウィンドウからの再読み込み
IntelliJ IDEAでGradleプロジェクトを再読み込みするには、右側のGradleツールウィンドウを開き、リロードアイコン（象のアイコン）をクリックします。ショートカットは⌘⇧I（macOS）またはCtrl+Shift+O（Windows/Linux）です。
build.gradleやbuild.gradle.ktsを変更すると、IntelliJ IDEAが「リロードが必要」と通知を表示します。再読み込み後、依存関係が「外部ライブラリ」セクションに反映されます。
依存関係リフレッシュの実行方法
IntelliJ IDEA内で--refresh-dependencies相当の操作を行うには、Gradleツールウィンドウの「Reload All Gradle Projects」を使用します。この操作はコマンドラインでの--refresh-dependenciesに相当する依存関係リフレッシュを実行します。
ただし、確実に--refresh-dependenciesを実行したい場合は、ターミナルから直接コマンドを実行する方法が明確です。IDEの操作だけでは、どの程度のリフレッシュが行われたかが分かりにくい場合があります。
Gradle VM optionsの設定場所
IntelliJ IDEAでは、「Settings > Build, Execution, Deployment > Build Tools > Gradle」の画面で「Gradle VM options」を設定できます。ここで指定した内容は、IDE内から起動するGradleデーモンのJVMメモリ設定として使用されます。
注意すべき点として、IDEのGradle設定はgradle.propertiesの設定を上書きすることがあります。IDE内で期待どおりのメモリ設定にならない場合は、どちらの設定が有効になっているかを確認してください。
要点：IDEの再読み込みはリロードアイコン、依存関係リフレッシュは「Reload All Gradle Projects」。どちらの設定が有効か確認しながら使用しましょう。
Gradleのメモリ不足エラー発生時の対処法と設定値
メモリ不足エラーの主な種類と原因
Gradleのビルド中に発生するメモリ不足エラーには、主に以下の種類があります。
| エラーメッセージ | 原因 | 対処の方向性 |
|---|---|---|
| java.lang.OutOfMemoryError: Java heap space | ヒープサイズ不足 | -Xmx値を増やす |
| GC overhead limit exceeded | ガベージコレクション過剰 | ヒープサイズ増加、GC設定変更 |
| Could not reserve enough space for object heap | 物理メモリ不足・断片化 | -Xmx値を下げる、他アプリ終了 |
Gradleデーモンのデフォルト最大ヒープサイズは512MB（-Xmx512m）、デフォルトMetaspaceは384MB（-XX:MaxMetaspaceSize=384m）です。大規模プロジェクトではこのデフォルト値では不足することがあります。
gradle.propertiesでの設定方法
メモリ不足を解決する標準的な方法は、gradle.propertiesにorg.gradle.jvmargsを設定することです。推奨される設定例は以下のとおりです。
- プロジェクト直下またはユーザーホーム（
~/.gradle/gradle.properties）のgradle.propertiesを開く - 以下の行を追加または修正する
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
ここで、-Xmxは最大ヒープサイズ、-XX:MaxMetaspaceSizeはMetaspace上限、-XX:+HeapDumpOnOutOfMemoryErrorはOOM発生時にヒープダンプを生成する指定です。
設定変更後に必要な手順
gradle.propertiesを変更しただけでは設定は反映されません。以下の手順でデーモンを再起動する必要があります。
./gradlew --stop（またはgradle --stop）でデーモンを停止する- 再度ビルドを実行して、新しい設定でデーモンが起動することを確認する
また、org.gradle.jvmargsの一部のみを上書きすると、他のデフォルト設定がクリアされることがあります。主要なJVM引数はセットで設定することをおすすめします。
要点：デフォルトは-Xmx512m。メモリ不足ならgradle.propertiesでorg.gradle.jvmargsを設定し、デーモンを再起動する。
Gradleのリフレッシュやメモリ設定で動かない場合の確認ポイント
設定が反映されない場合の確認ポイント
メモリ設定やリフレッシュが期待どおりに動作しない場合、まずどの設定ファイルが読み込まれているかを確認してください。ユーザーホームのgradle.propertiesとプロジェクト直下のgradle.propertiesが両方存在する場合、優先順位によって意図しない設定が使われている可能性があります。
また、IntelliJ IDEAを使用している場合、IDEの「Gradle VM options」設定がgradle.propertiesを上書きしているケースがあります。IDEの設定画面で「Gradle VM options」欄が空になっているか、意図した値が入っているかを確認してください。
GRADLE_OPTSとの混同に注意
環境変数GRADLE_OPTSやJAVA_OPTSを設定しても、ビルドを実行するデーモンのメモリは増えません。これらの環境変数はGradleクライアントVM（コンソール出力を表示するプロセス）にのみ影響し、実際のビルド処理はデーモンが別プロセスとして実行します。
ビルド自体のメモリを増やすには、必ずorg.gradle.jvmargsを使用してください。GRADLE_OPTSに-Xmxを指定しても効果がないため、この混同が原因で「設定したのに動かない」という状況が発生しがちです。
それでも解決しない場合のチェックリスト
以下の項目を順番に確認することで、多くの問題は解決できます。
- Gradle Wrapperが存在するか：
gradlewまたはgradlew.batがあるか確認する - Javaのバージョン互換性：Gradleを実行するにはJDK 17以上が必要です。
- デーモンの状態：
./gradlew --statusでデーモンの状態を確認し、必要なら--stopで停止する - エラーメッセージの種類：ヒープ不足なのか、物理メモリ不足なのかで対処が異なる
- ヒープダンプの生成：
-XX:+HeapDumpOnOutOfMemoryErrorを設定してOOM発生時に解析する
要点：設定ファイルの優先順位、GRADLE_OPTSとの混同、デーモンの再起動、Javaバージョン互換性を順に確認しましょう。
“`
まとめ
よくある質問
Q: Gradleのリフレッシュとは何ですか？
A: Gradleのリフレッシュには、IDEでGradleプロジェクトを再読み込みする操作と、依存関係のキャッシュを更新する–refresh-dependenciesオプションの2種類があります。前者はbuild.gradleの変更を反映するため、後者はリモートリポジトリの最新版を取得するために使用します。
Q: Gradleで依存関係を強制的に更新するコマンドは？
A: 「./gradlew –refresh-dependencies」コマンドを実行すると、キャッシュを迂回してリモートリポジトリの更新版をチェックします。変更が検出された場合のみダウンロードが行われ、不要なダウンロードを避けることができます。
Q: IntelliJ IDEAでGradleプロジェクトを再読み込みする方法は？
A: IntelliJ IDEAでは、Gradleツールウィンドウのリロードアイコンをクリックするか、ショートカットキー（macOSでは⌘⇧I、Windows/LinuxではCtrl+Shift+O）で再読み込みできます。build.gradleを変更すると、IntelliJがリロードを促す通知を表示します。
Q: Gradleのメモリ不足エラーを解決するにはどうすればいいですか？
A: プロジェクト直下のgradle.propertiesに「org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError」のように設定を追加します。設定後は「./gradlew –stop」でGradleデーモンを停止してから再実行してください。
Q: Gradleのメモリ設定はどのファイルに書けばいいですか？
A: プロジェクト直下のgradle.propertiesまたはユーザーホームディレクトリの~/.gradle/gradle.propertiesに設定を記述します。IDEのGradle VM optionsはgradle.propertiesの設定を上書きすることがあるため、両方の設定を確認してください。
