Gradleのバージョン確認方法と最新版へのアップデート手順を徹底解説

Gradleバージョンの確認方法：システムとプロジェクトでどう違う？

システムにインストールされたGradleのバージョンを確認する

Gradleはシステム全体にインストールして使う方法と、プロジェクトごとにWrapperで使う方法の2種類があります。システムにインストールしたGradleのバージョンを確認するには、ターミナルでgradle -vまたはgradle --versionを実行します。このコマンドはGradleバージョン、ビルド時間、リビジョン、実行中のJVMやGroovy、Kotlin、Antの各バージョンをまとめて表示します。Gradleが正しくインストールされているか、どのバージョンがPATH上で有効になっているかを確認する際に便利です。（出典：Gradle公式「Installing Gradle」）

プロジェクトで使われているGradleバージョンをWrapperで確認する

Gradle Wrapperを使っているプロジェクトでは、システムのGradleとプロジェクトのGradleが異なる場合があります。プロジェクトのルートディレクトリで./gradlew --version（Windowsはgradlew.bat --version）を実行すると、そのプロジェクトが固定しているGradleバージョンが表示されます。Gradleはプロジェクトごとに使用バージョンを固定できるWrapperの利用を公式に推奨しており、開発者全員とCI環境で同じバージョンを使うための標準的な方法です。（出典：Gradle公式「Gradle Wrapper Basics」）

gradle-wrapper.propertiesファイルで直接確認する

Wrapperで指定されたGradleバージョンは、設定ファイルにも記載されています。プロジェクト内のgradle/wrapper/gradle-wrapper.propertiesを開き、distributionUrlプロパティを確認してください。例えばdistributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zipのように、URL内にバージョン番号が含まれています。コマンドを実行しなくてもバージョンを特定できるため、CI設定の確認やトラブルシューティングの際に役立ちます。（出典：Gradle公式「Gradle Wrapper」）

システムのGradleバージョンは「gradle -v」、プロジェクトのバージョンは「./gradlew –version」か「gradle-wrapper.properties」で確認します。プロジェクトでは常にWrapperのバージョンを優先してください。

最新のGradleバージョンを確認する方法と公式リリース情報の見方

公式リリースページで最新安定版を確認する

Gradleの最新安定版は公式リリースページで確認するのが最も確実です。Gradle公式サイトのリリースページ（gradle.org/releases）には、現行の最新安定版と過去のリリース一覧が掲載されています。2026年8月時点の最新安定版はGradle 9.6.1で、2026年6月26日にリリースされました。これは9.6.0のパッチリリースであり、公式は9.6.1へのアップグレードを推奨しています。記事やブログで見かける古いバージョン情報に惑わされず、必ず公式ページで確認してください。（出典：Gradle公式「Gradle Releases」）

services.gradle.orgのAPIで自動的に最新版を確認する

最新バージョンをプログラム的に確認したい場合は、Gradleが提供するバージョンAPIが使えます。https://services.gradle.org/versions/currentにアクセスすると、最新バージョンの情報がJSON形式で取得できます。JSONにはversion、buildTime、snapshot、downloadUrlなどのキーが含まれます。シェルスクリプトからcurl -s https://services.gradle.org/versions/currentを実行することで、CIパイプラインや自動化ツールに最新版情報を組み込めます。（出典：Gradle公式「services.gradle.org/versions/current」）

リリースノートと今後のリリース予定を読む

バージョンアップを検討する際は、リリースノートで変更点を確認することが重要です。各リリースには改善点や非推奨（deprecation）警告、削除予定APIなどが記載されています。例えばGradle 9.5.0ではWrapperダウンロードのリトライ機能が追加され、9.4.0ではJava 26サポートが導入されました。また、次期メジャーバージョンのGradle 10は2026年Q4から2027年Q1頃のリリースが見込まれており、9系で非推奨となったAPIは10で削除される予定です。（出典：Gradle公式「Gradle 9.5.0 Newsletter」「Apache Kafka JIRA KAFKA-20102」）

最新版の確認は公式リリースページ（gradle.org/releases）が基本です。自動化したい場合はservices.gradle.orgのAPIを利用し、アップグレード前にはリリースノートで非推奨APIや削除予定を確認しましょう。

Gradleのバージョンアップ手順：Wrapperを使った安全な更新方法

WrapperコマンドでGradleバージョンを更新する

プロジェクトのGradleバージョンを更新するには、Wrapperコマンドを使うのが公式推奨の方法です。プロジェクトのルートディレクトリで./gradlew wrapper --gradle-version=9.6.1のように実行します。このコマンドはgradle-wrapper.propertiesのバージョン指定を更新し、gradlewとgradlew.batスクリプトも更新します。更新後は./gradlew --versionを実行して、新しいバージョンが正しくダウンロードされたことを確認してください。（出典：Gradle公式「Gradle Wrapper Documentation」）

Wrapper生成とディストリビューション指定

プロジェクトにWrapperがない場合は、まず生成する必要があります。システムにGradleがインストールされていれば、gradle wrapperコマンドでWrapperを生成できます。生成されるファイルはgradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar、gradle/wrapper/gradle-wrapper.propertiesの4つです。更新時には--distribution-type bin（バイナリのみ）や--gradle-distribution-sha256-sum（SHA-256ハッシュ指定）などのオプションを使うことで、ダウンロードするディストリビューションを細かく制御できます。（出典：Gradle公式「Gradle Wrapper Documentation」）

アップデート時の注意点と確認事項

バージョンアップ前に、必ず互換性マトリクスとアップグレードガイドを確認してください。Gradleを実行するJDKバージョンが新しいGradleに対応しているかを確認し、メジャーバージョンをまたぐ移行（例：8.xから9.x）では、公式のアップグレードガイドに従うことが重要です。更新後は以下の手順で進めます。

1. 変更した4つのファイル（gradlew、gradlew.bat、gradle-wrapper.jar、gradle-wrapper.properties）をGitなどのバージョン管理システムにコミットする
2. ビルドを実行して非推奨警告が表示されていないか確認する
3. 問題がなければチーム全体に新しいバージョンを共有する

非推奨警告はGradle 10で削除されるAPIの予告であるため、放置せずに対処することをおすすめします。（出典：Gradle公式「Gradle Wrapper Documentation」「Gradle Compatibility Matrix」）

更新は「./gradlew wrapper –gradle-version=バージョン」で行い、変更した4ファイルを必ずコミットします。メジャーバージョンをまたぐ場合はアップグレードガイドの確認が必須です。

GradleとJavaの互換性：バージョン選定で押さえるべきポイント

Gradle実行環境に必要なJDKバージョン

現行のGradleを実行するには、JDK 17以上が必要です。古い記事にある「JDK 8で動く」という説明は現行版には適用できません。2026年8月時点の互換性マトリクスでは、Gradleの実行環境としてJava 17からJava 26までがサポートされています。これは「Gradle自体を動かすためのJava」の話であり、「プロジェクトがコンパイル対象とするJava」とは別の話です。Gradleをインストールする前に、自分が使っているJDKが要件を満たしているか確認してください。（出典：Gradle公式「Compatibility Matrix」）

Javaバージョン別の必要Gradleバージョン

新しいJavaバージョンでGradleを実行するには、対応するGradleバージョンが必要です。以下の表は、Gradleを実行する環境のJDKバージョンと、必要な最小Gradleバージョンの対応を示しています。

これは「コンパイル対象のJava」ではなく「Gradleを実行するJava」の話です。混同しないように注意してください。（出典：Gradle公式「Compatibility Matrix」）

Java Toolchainsで実行環境とビルド対象を分離する

Gradleを実行するJDKと、プロジェクトのコンパイルやテストに使うJava環境は分離できます。Java Toolchainsという機能を使うと、Gradle自体はJDK 17で動かしながら、プロジェクトのビルドにはJava 21やJava 26を指定できます。ビルドスクリプトでjava.toolchainを設定することで、Gradleが自動的に適切なJDKを探して使用します。これにより、開発環境のJDKを切り替えずに複数のJavaバージョンを扱えます。（出典：Gradle公式「Java Toolchains」）

「Gradleを実行するJDK」と「ビルド対象のJava」は別物です。互換性マトリクスで実行環境の要件を確認し、Java Toolchainsでビルド対象を柔軟に指定しましょう。

Gradle Versions PluginとVersion Catalogで依存関係のバージョン管理

Gradle自身のバージョンと依存ライブラリのバージョンは別物

Gradleのバージョン更新と、プロジェクトが使用するライブラリのバージョン更新は別の作業です。Gradle自身のバージョンはWrapperで管理しますが、依存ライブラリ（例：JUnit、Jacksonなど）のバージョンはビルドスクリプトで指定します。両者を混同すると、./gradlew --versionで確認できるのはGradleのバージョンだけであり、依存ライブラリの更新状況は別途確認する必要があるという点を見落としがちです。（出典：Gradle公式「Gradle User Manual」）

Gradle Versions Pluginで依存関係の更新を確認する

依存ライブラリに新しいバージョンがないかを自動確認するには、Gradle Versions Pluginが便利です。ben-manes/gradle-versions-pluginを導入し、./gradlew dependencyUpdatesを実行すると、プロジェクト内の依存関係で利用可能な新しいバージョンが一覧表示されます。安定版のみを対象にする設定や、特定のライブラリを除外する設定も可能です。定期的にこのタスクを実行することで、セキュリティ修正やバグ修正を含むライブラリ更新の取りこぼしを防げます。

Version Catalogで依存関係を一元管理する

GradleのVersion Catalog機能を使うと、依存関係とバージョンを1つのファイルで管理できます。gradle/libs.versions.tomlというファイルに依存ライブラリのバージョンをまとめて記述し、ビルドスクリプトから参照する仕組みです。Kotlin DSLでは型安全なアクセサが利用でき、IDEの自動補完やコンパイル時のチェックが効きます。複数モジュールで構成されるプロジェクトでは、バージョンの一元管理によって更新漏れやバージョンの不整合を防ぎやすくなります。Version CatalogとVersions Pluginは併用できますが、ツールによってはカタログ形式に未対応の場合もあるため、導入時は互換性を確認してください。

Gradle自身のバージョンはWrapperで、依存ライブラリのバージョンはVersions PluginやVersion Catalogで管理します。両者は別物であることを意識し、それぞれ適切なツールを選びましょう。

“`