GradleとJavaの互換性を理解するための基本知識

GradleはJava実行環境の上で動くビルドツール

Gradleは、JavaなどのJVMプロジェクトにおけるコンパイル、テスト、依存関係管理、JAR/WARへのパッケージングなどを自動化するオープンソースのビルドツールです。Gradle自体もJavaで動作するため、実行するにはJDKが必要です。2026年8月時点では、Gradleを実行するために最低限JDK 17以上が必須となっています（出典：Gradle「Installing Gradle」）。

GradleはJavaコンパイラそのものではなく、Javaコンパイルなどの処理をタスクとして構成・実行する役割を持ちます。そのため「Gradleのバージョン」と「Javaのバージョン」は別物として理解することが重要です。

「Gradleを実行するJava」と「コンパイル対象のJava」は別

GradleとJavaの互換性を考える際、混同しやすい2つの概念があります。1つはGradle自体を実行するためのJDKバージョン、もう1つはプロジェクトのソースコードをコンパイルする対象のJavaバージョンです。たとえば、Gradle 9.6.1をJava 21の実行環境で動かしながら、コンパイル対象はJava 17に設定する、といった構成が可能です。

この分離を実現する仕組みがJava Toolchainsです。これにより、実行環境とコンパイル対象を独立して指定できます。

Gradleバージョンごとに必要なJDKが異なる

Gradleのバージョンが上がるにつれて、サポートされるJavaの範囲も変化します。現在の互換性表では、Gradleの実行環境としてJava 17からJava 26までがサポートされています（出典：Gradle「Compatibility Matrix」）。

古い記事にある「JDK 8があればGradleを実行できる」という説明は現行版には適用できません。新しくプロジェクトを始める場合は、必ず最新の互換性表を確認するようにしましょう。

要点：Gradleを実行するJDKと、コンパイル対象のJavaバージョンは別物。現行GradleはJDK 17以上で動作する。

—

GradleとJavaのバージョン対応表：実行環境とコンパイル対象の違い

実行環境としてのJava対応表

Gradleを実行するために必要なJDKバージョンは、Gradleのバージョンによって異なります。Java 26でGradleを実行するにはGradle 9.4.0以降、Java 21ならGradle 8.5以降、Java 17ならGradle 7.3以降が必要です（出典：Gradle「Compatibility Matrix」）。

Java実行環境 必要な最小Gradleバージョン
Java 26 Gradle 9.4.0
Java 25 Gradle 9.0.0
Java 24 Gradle 8.14.0
Java 23 Gradle 8.10.0
Java 22 Gradle 8.7.0
Java 21 Gradle 8.5.0
Java 17 Gradle 7.3.0

2026年8月時点の最新安定版はGradle 9.6.1で、Java 17〜26を実行環境としてサポートしています。

コンパイル対象としてのJava指定

コンパイル対象のJavaバージョンは、Gradleの実行環境とは独立して指定できます。JavaプラグインではsourceCompatibilityやtargetCompatibility、またはoptions.releaseを使ってコンパイル対象を設定します。

ただし、より推奨される方法はJava Toolchainsの利用です。Toolchainsを使うと、Gradleが指定されたバージョンのJDKを自動的に検出またはダウンロードして、コンパイルやテストに使用します。これにより、開発者ごとにJDKのインストール状況が異なっていても一貫したビルドが可能になります（出典：Gradle「Gradle User Manual」）。

Version Catalogで依存関係のバージョンを一元管理

Javaのバージョンだけでなく、依存ライブラリのバージョン管理にも互換性の考え方が重要です。GradleではVersion Catalog（libs.versions.toml）を使うことで、依存関係のバージョンを一元的に管理できます。

これはJavaのバージョン対応とは直接関係しませんが、プロジェクト全体の互換性を保つための補助的な仕組みとして知っておくと便利です。JavaのバージョンとGradleのバージョンの対応に加えて、ライブラリが求めるJavaバージョンにも注意を払いましょう。

要点：Gradleの実行環境とコンパイル対象は分けて考える。Java 26で実行するならGradle 9.4.0以降が必要。

—

GradleでJavaバージョンを指定する方法：Java ToolchainsとローカルJDK指定

Java Toolchainsの基本的な使い方

Java Toolchainsは、Gradleを実行しているJDKとは別に、コンパイルやテストに使用するJDKを指定できる機能です。build.gradleまたはbuild.gradle.ktsに以下のように記述します。

// Kotlin DSL
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Gradleは指定されたバージョンのJDKをローカル環境から検出し、見つからない場合は設定に応じて自動ダウンロードも可能です。これにより、開発環境ごとのJDK差異によるビルドの違いを防げます（出典：Gradle「Gradle User Manual」）。

Java Toolchainsを使用しない従来の指定方法

Toolchainsが導入される以前からある方法として、sourceCompatibilityとtargetCompatibilityによる指定があります。これはコンパイル時のソース互換性とバイトコード互換性を設定するものです。

// Groovy DSL
sourceCompatibility = '17'
targetCompatibility = '17'

ただしこの方法では、実際に使用するJDKが実行環境のものに依存するため、Java 21でGradleを実行しながらJava 17向けにコンパイルする際に、微妙な互換性の問題が生じる可能性があります。新規プロジェクトではJava Toolchainsの利用が推奨されます。

ローカルJDKの指定

Gradleが使用するJDKを明示的に指定するための仕組みとして、ローカルJDKのパス指定があります。これはgradle.propertiesや環境変数ではなく、特定のGradleディストリビューションやIDE連携において使用されることがあります。

一般的なプロジェクトでは、この指定よりもJava Toolchainsを使う方が柔軟で推奨されます。ローカルに複数のJDKがインストールされている場合、Toolchainsが自動的に適切なバージョンを検出してくれます。どうしても特定のJDKに固定したい場合に、ローカルJDKのパス指定を検討しましょう。

要点：Java Toolchainsを使えば、Gradle実行環境とコンパイル対象のJDKを分離できる。新規プロジェクトではToolchainsが推奨。

—

Gradle WrapperとGradle Home：プロジェクトで使うGradleバージョンの固定方法

Gradle Wrapperでバージョンを固定する

Gradle Wrapperは、プロジェクトごとに使用するGradleバージョンを固定する仕組みです。Gradle公式は、システムにインストールしたGradleを直接使うよりも、Wrapperの利用を推奨しています（出典：Gradle「Gradle Wrapper Basics」）。

Wrapperを使うと、開発者全員が同じGradleバージョンでビルドでき、CI環境でも再現性が確保されます。Wrapperが含まれるプロジェクトでは、システムにGradleをインストールしていなくても、gradlewまたはgradlew.batを実行するだけで必要なGradleが自動取得されます。

gradle-wrapper.propertiesでバージョンを管理

Gradle Wrapperの設定はgradle/wrapper/gradle-wrapper.propertiesに記述されています。このファイル内のdistributionUrlに使用するGradleのバージョンが指定されています。

distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip

Gradleのバージョンを変更するには、このURLを書き換えるか、gradle wrapper --gradle-version 9.6.1コマンドを実行します。Wrapper関連のファイルはgradlew、gradlew.bat、gradle-wrapper.properties、gradle-wrapper.jarの4つです。

Gradle Homeとローカルインストールの違い

Gradle Homeは、システムにインストールされたGradleの場所を指します。gradleコマンドを直接使う場合はこのGradle Homeのバージョンが使用されますが、Wrapperを使う場合はプロジェクトごとのGradleが優先されます。

既存プロジェクトを扱う際は、まずgradlewの有無とgradle-wrapper.propertiesの内容を確認しましょう。Wrapperがあるプロジェクトでは、ローカルにインストールしたGradleではなくWrapperを使うのが基本です。これによりバージョン差異によるビルド失敗を防げます。

要点：Gradle WrapperはプロジェクトごとのGradleバージョンを固定する公式推奨の仕組み。Wrapperがある場合はそれを優先して使う。

—

VS CodeでGradleとJavaを使う際の設定とLombok連携のポイント

VS CodeのJava拡張機能とGradle連携

VS CodeでJava開発を行うには、Extension Pack for Javaを導入するのが基本です。この拡張機能パックには、Gradleプロジェクトを認識するためのGradle for Java拡張機能も含まれています。

プロジェクトを開くと、VS Codeがbuild.gradleまたはbuild.gradle.ktsを読み取り、依存関係やソースセットを自動的に認識します。Gradle Wrapperが存在するプロジェクトでは、VS CodeもWrapperを使ってビルドやタスク実行を行います。

JDKの選択とJava Toolchainsの関係

VS CodeでJDKのバージョンを指定するには、設定のjava.configuration.runtimesを使用します。ここにインストール済みのJDKパスを登録しておくことで、プロジェクトごとに使用するJDKを切り替えられます。

GradleプロジェクトでJava Toolchainsを設定している場合、VS CodeはToolchainsの設定を参照して適切なJDKを選択します。そのため、VS Code側で指定するJDKはGradleの実行環境としてのJDKであり、コンパイル対象のJDKはToolchainsが管理する、という役割分担になります。

Lombok導入時の設定ポイント

JavaプロジェクトでLombokを使用する場合、Gradleの依存関係にLombokを追加します。VS CodeでLombokを利用するには、Lombok Annotations Support for VS Code拡張機能の導入が推奨されます。

Lombokはコンパイル時にアノテーションを処理するため、Gradleのビルド自体はLombokが依存関係にあれば正常に動作します。VS Code上でのエディタ支援（エラー表示や補完）を正しく機能させるためには、拡張機能の導入とJDKのバージョン整合に注意が必要です。Javaの新しいバージョンを使用する場合は、Lombokの対応バージョンも確認しましょう。

要点：VS CodeではJava拡張機能パックとGradle for Javaを導入し、ToolchainsとJDK設定の役割分担を理解しておくとスムーズに連携できる。