Gradleとは？インストール前に知っておきたい基礎知識

Gradleはビルド自動化ツール

Gradleは、JavaなどのJVMプロジェクトで利用できるビルド自動化ツールです。コンパイル、テスト実行、外部ライブラリの取得、依存関係の解決、JARなどへのパッケージングをまとめて自動化できます。Gradle自体がJavaコンパイラではなく、これらの処理をタスクとして構成・実行する役割を担います。

ビルド設定はGroovy DSL（build.gradle）またはKotlin DSL（build.gradle.kts）で記述します。Mavenのpom.xmlがXML形式であるのに対し、Gradleは柔軟なDSLでビルド処理を記述できるのが特徴です。オープンソースであり無料で利用できます。（出典：Gradle「Gradle Build Tool Features」）

Gradleの実行にはJDK 17以上が必要

Gradleを実行するにはJDK 17以上が必須です。2026年8月時点の互換性表では、Java 17〜26をGradleの実行環境としてサポートしています。JDKが入っていない場合は、まずJavaの開発環境を整える必要があります。

注意したいのは、Gradleを実行するJDKのバージョンとプロジェクトのコンパイル対象となるJavaバージョンは別物だという点です。GradleにはJava Toolchainsという仕組みがあり、実行環境とは別にコンパイル用のJavaバージョンを指定できます。Java 26でGradleを実行するにはGradle 9.4.0以降、Java 21ならGradle 8.5以降が必要です。（出典：Gradle「Compatibility Matrix」）

Gradle Wrapperの利用が公式推奨

Javaプロジェクトでは、Gradle本体を手動インストールするよりGradle Wrapperを利用することが公式推奨です。Wrapperとは、プロジェクトごとに使用するGradleバージョンを固定し、必要に応じて自動取得・実行する仕組みです。

Wrapperを使えば、開発者全員が同じGradleバージョンを使用でき、CI環境でも同じ条件でビルドできます。Gradle Wrapperが含まれるプロジェクトであれば、システムにGradleをインストールしなくてもビルド可能です。（出典：Gradle「Gradle Wrapper Basics」）

要点：GradleはJDK 17以上で動作するビルド自動化ツール。既存プロジェクトでは手動インストールよりWrapperの利用が推奨される。

Windows・Mac・LinuxでのGradleインストール方法

OS共通：パッケージマネージャを利用する方法

Gradleはパッケージマネージャ経由でインストールするのが一般的です。公式が推奨するのはSDKMAN!で、Gradle本体がSDKMAN!で管理・展開されています。macOSやLinux、WindowsのWSL環境ではsdk install gradleで最新版を導入できます。

特定バージョンを指定する場合はsdk install gradle 9.6.1のように実行します。公式が注意を呼びかけているとおり、Linuxのaptなどが配布するGradleは公式版と互換性がない、または不完全な修正版の可能性があるため、SDKMAN!の利用が安全です。（出典：Gradle「Installing Gradle」）

OS別のインストールコマンド

各OSで利用できるパッケージマネージャとコマンドは以下の通りです。

OS パッケージマネージャ コマンド
macOS Homebrew brew install gradle
macOS MacPorts sudo port install gradle
Windows Scoop scoop install gradle
Windows Chocolatey choco install gradle
Windows winget winget install gradle
Unix系全般 SDKMAN! sdk install gradle

WindowsのWSL環境ではSDKMAN!を利用できます。インストール後はgradle -vまたはgradle --versionでバージョンとJDKを確認します。（出典：Gradle「Installing Gradle」）

ZIPをダウンロードして手動インストールする方法

パッケージマネージャを使わず、ZIPファイルを展開してインストールする方法もあります。手順は以下の通りです。

  1. 公式配布サイトからZIPをダウンロードする（例：gradle-9.6.1-bin.zip）
  2. 任意のディレクトリに解凍する（例：WindowsならC:\gradle-9.6.1、Linux/macOSなら/opt/gradle-9.6.1）
  3. 環境変数GRADLE_HOMEに解凍先を設定し、binディレクトリをPATHに追加する

Linux/macOSでは.bashrcや.zshrcにexport GRADLE_HOME=/opt/gradle-9.6.1とexport PATH=$GRADLE_HOME/bin:$PATHを追記します。この方法なら、アップグレード時にGRADLE_HOMEのパスを変更するだけで済みます。（出典：Gradle「Installing Gradle」）

要点：SDKMAN!が公式推奨のインストール方法。手動インストールではGRADLE_HOMEとPATHの設定が必要。

Gradleのダウンロード方法と配布ファイルの選び方

公式ダウンロードURLとバージョン確認

GradleのZIPファイルはhttps://services.gradle.org/distributions/から直接ダウンロードできます。2026年8月時点の最新安定版はGradle 9.6.1（2026年6月26日リリース）です。9.6.0のパッチリリースであり、公式は9.6.1へのアップグレードを推奨しています。

すべてのバージョン一覧とSHA-256チェックサムは、公式リリースページ（gradle.org/releases/）で確認できます。記事の内容が古くならないよう、導入前に最新版が変わっていないか確認することをおすすめします。（出典：Gradle「Gradle 9.6.1 Release Notes」）

binとallの違いを理解する

GradleのZIP配布ファイルには「bin」と「all」の2種類があります。

配布タイプ 内容 特徴
-bin.zip バイナリのみ ファイルが小さくダウンロードが速い。公式推奨
-all.zip バイナリ＋ドキュメント＋ソースコード ファイルが大きい。ソースを参照したい場合に便利

通常の利用では-bin.zipが公式推奨です。「allのほうが高機能」ではなく、単にドキュメントとソースが同梱されるだけの違いです。ダウンロードURLの例はhttps://services.gradle.org/distributions/gradle-9.6.1-bin.zipとなります。

ダウンロード後の検証と注意点

ZIPをダウンロードして解凍したら、gradle -vでバージョンとJDKを確認します。Gradleが正しく起動すれば、Gradleバージョン、JVMのバージョン、OS情報などが表示されます。JDK 17以上がインストールされていない場合は、ダウンロードしても実行できないため注意が必要です。

また、GradleにはKotlinとGroovyがバンドルされているため、別途インストールする必要はありません。複数のJDKがある場合は、JAVA_HOME環境変数でGradleが使用するJDKを指定できます。（出典：Gradle「Installing Gradle」）

要点：最新版は9.6.1。配布ファイルはbin（バイナリのみ）が公式推奨で、ダウンロードはservices.gradle.orgから行う。

Gradle Wrapperを利用する方法とアップグレード手順

Wrapperの基本とファイル構成

Gradle Wrapperは、プロジェクトが使用するGradleバージョンを固定し、自動取得・実行する仕組みです。代表的なファイルは以下の通りです。

  • gradlew：Linux/macOS用の実行スクリプト
  • gradlew.bat：Windows用の実行スクリプト
  • gradle/wrapper/gradle-wrapper.properties：Gradleバージョンや配布URLを指定
  • gradle/wrapper/gradle-wrapper.jar：Wrapperの実行に必要なJARファイル

既存プロジェクトにこれらのファイルがある場合、システムにGradleをインストールする必要はありません。JDK 17以上があれば./gradlew（Windowsではgradlew.bat）でビルドできます。

Wrapperを新規作成する方法

新規プロジェクトでWrapperを生成するには、Gradleがインストールされた環境で以下のコマンドを実行します。

  1. gradle wrapper：現在のGradleバージョンでWrapperを生成
  2. gradle wrapper --gradle-version 9.6.1：特定バージョンを指定
  3. gradle wrapper --distribution-type bin：配布タイプを指定（binが既定）

生成されたWrapperファイルはすべてバージョン管理（Git）にコミットすることが推奨されています。ただし、gradle-wrapper.jarをコミットするかどうかはプロジェクトの運用方針によります。公式はコミットを推奨していますが、チームのルールに従って判断してください。（出典：Gradle「Gradle Wrapper」）

Wrapperのアップグレード手順

プロジェクトのGradleバージョンを上げるには、Wrapperのアップグレードコマンドを使用します。

  • ./gradlew wrapper --gradle-version latest：最新版へ更新
  • ./gradlew wrapper --gradle-version 9.6.1：特定バージョンへ更新

gradle-wrapper.propertiesのdistributionUrlは末尾が-bin.zipであるべきです。直接このファイルを編集してバージョンを変更することもできます。Gradle 9.6.0から9.6.1へのようなパッチアップデートは、修正内容を確認の上、早めに行うことが推奨されます。（出典：Gradle「Gradle Wrapper Basics」）

要点：WrapperはプロジェクトごとにGradleバージョンを固定する仕組み。既存プロジェクトではインストール不要で、アップグレードはwrapperコマンドで行う。

Gradleインストール時の注意点とトラブル対処法

Javaバージョンに関する注意点

Gradleのインストールで最も多いトラブルはJavaバージョンの不一致です。現在のGradleはJDK 17以上が必要で、古い記事にある「JDK 8で動作する」という情報は現行版には適用できません。まずjava -versionでJDKバージョンを確認しましょう。

複数のJDKがインストールされている場合、GradleはPATH上のJDKを使用します。意図したJDKを使わせたい場合はJAVA_HOME環境変数を設定します。Java 26でGradleを実行するにはGradle 9.4.0以上が必要なため、JDKを最新にした場合はGradleのバージョンも確認が必要です。（出典：Gradle「Compatibility Matrix」）

Linuxのパッケージマネージャに関する注意点

Linuxのaptなどが配布するGradleは、公式版と互換性がない、または不完全な修正版の可能性があると公式が明記しています。Ubuntuなどでapt install gradleを使用すると、古いバージョンや修正版がインストールされる場合があります。バージョンが古いと、JDKの互換性問題や意図しない動作が発生しやすくなります。

Linux環境ではSDKMAN!の利用が確実です。SDKMAN!はGradle公式が管理・展開しているパッケージマネージャで、常に最新版をインストールできます。どうしてもaptを使う必要がある場合は、インストール後にgradle -vでバージョンを確認し、最新版かどうかを必ずチェックしてください。（出典：Gradle「Installing Gradle」）

インストールがうまくいかない場合の確認ポイント

gradleコマンドが認識されない場合は、以下の点を確認します。

  1. 環境変数GRADLE_HOMEとPATHが正しく設定されているか
  2. PATHに%GRADLE_HOME%\bin（Windows）または$GRADLE_HOME/bin（Linux/macOS）が含まれているか
  3. ターミナルを再起動してPATH設定を反映したか
  4. java -versionでJDK 17以上が確認できるか

既存プロジェクトの場合は、まずgradlewまたはgradlew.batの存在を確認しましょう。Wrapperがあるなら、システムへのGradleインストールは不要です。（出典：Gradle「Installing Gradle」）

要点：JDK 17以上が前提。Linuxのaptは公式版と異なる可能性があるためSDKMAN!を推奨。トラブル時はPATH設定とJDKバージョンを確認する。