“`html

Gradleとは？Mavenとの違いや基本概念をわかりやすく解説

Gradleの役割と基本概念

Gradleは、JavaなどのJVMプロジェクトで利用できるビルド自動化ツールです。ソースコードのコンパイル、テスト実行、外部ライブラリの取得、JARなどのパッケージング、アプリケーションの実行まで、開発に必要な一連の処理を自動化します。Gradle自体がJavaコンパイラではなく、これらの処理を「タスク」として構成・実行する役割を担います。

Gradleの主要概念として、Project（プロジェクト）、Task（タスク）、Dependency（依存関係）、Plugin（プラグイン）、Repository（リポジトリ）があります。特にTaskはGradleにおける処理単位で、コンパイルやテスト、JAR作成などがTaskとして実行されます。Javaプロジェクトでは「Java Plugin」を適用することで、これらのタスクが自動的に提供されます。

ビルド設定はGroovy DSLまたはKotlin DSLで記述します。従来からGroovy DSLが使われており、Kotlin DSLではbuild.gradle.ktsというファイル名を使用します。依存関係管理では、Maven CentralなどのMaven互換リポジトリからライブラリを取得し、推移的依存関係の解決にも対応しています。

要点：GradleはJavaのビルド作業を自動化するツールで、タスク単位で処理を実行します。ビルド設定はGroovyまたはKotlinのDSLで記述します。

Mavenとの違い

MavenもJavaで広く使われるビルド・依存関係管理ツールですが、Gradleとはビルド設定の記述方法が大きく異なります。MavenはXML形式のpom.xmlを使用するのに対し、GradleはGroovyまたはKotlinによるDSLで柔軟にビルド処理を記述できます。

「GradleはMavenの後継」「Mavenが古いのでGradleを使う」という単純な関係ではありません。両方とも現在も広く利用されており、プロジェクトの要件やチームの既存資産によって選択が変わります。GradleはMaven/Ivyのリポジトリ形式に対応しており、MavenからGradleへの移行機能も公式に用意されています。

ビルド速度についても「Gradleのほうが必ず速い」とは断定できません。Gradleには増分ビルド、ビルドキャッシュ、並列実行などの高速化機能がありますが、実際のビルド時間はプロジェクト構成や設定によって変わるためです。

Gradle Wrapperとは

Gradle Wrapperは、プロジェクトが使用するGradleバージョンを固定し、そのバージョンのGradleを必要に応じて自動取得・実行する仕組みです。公式でもJavaプロジェクトではWrapperの利用が推奨されています。

代表的なファイルは以下の通りです。

  • gradlew：Linux/macOS用スクリプト
  • gradlew.bat：Windows用スクリプト
  • gradle/wrapper/gradle-wrapper.properties：Gradleバージョン設定
  • gradle/wrapper/gradle-wrapper.jar：Wrapper実行用JAR

Wrapperを使えば、開発者全員が同じGradleバージョンを使用でき、CI環境でも同一バージョンでビルドできます。システムにGradleをインストールしていなくても、Wrapperが自動的に必要なGradleをダウンロードして実行するため、環境差異による問題を防げます。

Gradleをインストールする方法（Windows／macOS／Linux）

インストール前に確認すること

Gradleを実行するにはJDK 17以上が必要です。2026年8月時点の現行Gradle（9.x系）では、JDK 8や11では実行できません。まずjava -versionでインストール済みのJavaバージョンを確認してください。複数のJDKを入れている場合は、環境変数JAVA_HOMEで使用するJDKを指定できます。

なお、既存のGradleプロジェクトを扱う場合はインストール不要です。プロジェクトにGradle Wrapper（gradlew / gradlew.bat）が含まれていれば、Gradle本体をシステムにインストールせずにビルドできます。インストールが必要になるのは、新規プロジェクトをgradle initで作成する場合や、Wrapperのないプロジェクトを扱う場合です。（出典：Gradle公式「Installing Gradle」）

インストール済みかどうかはgradle -vまたはgradle --versionで確認できます。コマンドが認識されなければ未インストールです。

パッケージマネージャーを使ったインストール

初心者にはSDKMAN!またはHomebrewを使ったインストールが簡単です。OS別の主な方法は以下の通りです。

OS 方法 コマンド
Unix系（macOS/Linux等） SDKMAN!（公式推奨） sdk install gradle
macOS Homebrew brew install gradle
Windows Chocolatey choco install gradle
Windows winget winget install gradle
Windows Scoop scoop install gradle
Linux apt / dnf / snap sudo apt install gradle 等

SDKMAN!は複数バージョンの並行管理・切り替えが容易で、Gradle公式も推奨しています。一方、Linuxのapt等で配布されるGradleはバージョンが古いことが多く、公式版と一致しない場合があるため注意が必要です。最新版を確実に使いたい場合はSDKMAN!または手動インストールを選びましょう。（出典：Gradle公式「Installing Gradle」）

手動インストールと検証

ZIPファイルをダウンロードして手動でインストールする手順は以下の通りです。

  1. https://services.gradle.org/distributions/gradle-<バージョン>-bin.zip からZIPをダウンロード（-bin.zipはバイナリのみの軽量版）
  2. 任意のディレクトリに解凍（例：/opt/gradle、WindowsならC:\Gradle）
  3. 環境変数GRADLE_HOMEに解凍先ディレクトリを設定
  4. PATHに$GRADLE_HOME/bin（Windowsなら%GRADLE_HOME%\bin）を追加
  5. gradle -vでバージョンが表示されることを確認

ダウンロード後は、公式リリースページに掲載されているSHA-256チェックサムと照合して改ざんがないことを確認するのが推奨されています。

要点：インストールはSDKMAN!またはHomebrewが簡単です。既存プロジェクトにWrapperがあればインストール不要で、JDK 17以上が前提条件です。

gradle initで新規Javaプロジェクトを作成する手順

gradle initの実行と対話式設定

gradle initコマンドは、新規Gradleプロジェクトの雛形を生成するためのコマンドです。プロジェクトタイプや実装言語、テストフレームワークなどを対話形式で選択できます。まずプロジェクト用のディレクトリを作成して移動し、gradle initを実行します。

  1. プロジェクトタイプを選択：Application（アプリ）、Library（ライブラリ）、Gradle plugin、Basicから選択
  2. 実装言語を選択：Java、Kotlinなどから選択
  3. ターゲットJavaバージョンを指定（最小7、デフォルト21）
  4. プロジェクト名を指定（デフォルトはディレクトリ名）
  5. アプリ構成を選択：Single application project または Application and library project
  6. ビルドスクリプトDSLを選択：Groovy（build.gradle）または Kotlin（build.gradle.kts）
  7. テストフレームワークを選択：JUnit Jupiter（デフォルト）、JUnit 4、TestNG、Spock

gradle initは対話式のほか、gradle init --type java-application --dsl kotlinのようにオプションを指定して非対話式で実行することも可能です。--typeにはjava-application、java-libraryなど、--dslにはgroovyまたはkotlinを指定します。（出典：Gradle公式「Gradle 第一部：プロジェクト初期化」）

生成されるプロジェクト構成

gradle init実行後、以下のような構成が生成されます。

  • gradle/wrapper/：gradle-wrapper.jarとgradle-wrapper.properties
  • gradlew：Linux/macOS用ラッパースクリプト
  • gradlew.bat：Windows用ラッパースクリプト
  • settings.gradle（または.kts）：プロジェクト名・子プロジェクト定義
  • app/：アプリケーションのソースコードとビルド設定
  • app/build.gradle（または.kts）：ビルド設定ファイル
  • app/src/main/java / app/src/test/java：ソース・テスト配置場所

Gradle Wrapperも同時に自動生成されるため、生成後はgradleコマンドではなく./gradlew（Windowsではgradlew.bat）を使用するのが基本です。settings.gradleにはrootProject.nameが設定されるため、プロジェクト名を固定できます。

なお、ルート直下にbuild.gradleを置くことは公式ガイドで推奨されていません。ビルド設定はapp/build.gradleなどのサブプロジェクト側に記述します。

プロジェクト作成後の確認ポイント

プロジェクト作成後は、Wrapperの存在とGradleバージョンを確認しましょう。gradle/wrapper/gradle-wrapper.propertiesに記載されたGradleバージョンが、このプロジェクトで使用されるバージョンです。生成時の最新安定版が設定されますが、必要に応じて後から更新できます。

次にjava -versionでJDKバージョンを確認します。Gradle 9.x系の実行にはJDK 17以上が必要です。Gradle本体を実行するJDKと、プロジェクトのコンパイル対象Javaバージョンは別物であることに注意してください。Java Toolchainsを使えば、Gradleを実行するJDKとコンパイルに使うJava環境を分離できます。

初回の./gradlew実行時は、WrapperがGradle本体をダウンロードするため時間がかかります。ダウンロードしたGradleは~/.gradle/wrapper/distsにキャッシュされるため、2回目以降は高速に実行できます。

Gradleの基本コマンド一覧（build、run、test、cleanなど）

よく使う基本コマンド

Gradleの基本操作でよく使うコマンドは以下の通りです。既存プロジェクトではgradleではなく./gradlew（Windowsではgradlew.bat）を使用します。

コマンド 用途 備考
./gradlew build コンパイル＋テスト＋パッケージング 依存タスクを自動実行
./gradlew run Javaアプリを実行 applicationプラグイン適用時
./gradlew test テスト実行 テスト結果はbuild/reportsに出力
./gradlew clean buildディレクトリ（生成物）を削除 clean buildで完全再構築
./gradlew tasks 利用可能なタスク一覧を表示 カテゴリ別に分類表示
./gradlew jar JAR作成 java-libraryプラグイン適用時

buildは最も基本的なコマンドで、コンパイル・テスト・JAR作成などの一連の処理をまとめて実行します。cleanは生成物の削除だけを行うため、完全に再構築したい場合はclean buildのように複数タスクをスペース区切りで指定します。

タスク一覧と詳細確認

Gradleではtasksコマンドで実行可能なタスクを確認できます。タスクは「build」「documentation」「verification」などのグループごとに分類されて表示されます。より詳細な情報を得るには、以下のコマンドが便利です。

  • ./gradlew tasks --all：隠れた内部タスク・ライフサイクルタスクも含めて表示
  • ./gradlew tasks --group="build"：特定グループのタスクのみ表示
  • ./gradlew help --task <タスク名>：特定タスクの詳細を表示
  • ./gradlew dependencies：依存関係ツリーを表示

dependenciesコマンドは、プロジェクトが依存しているライブラリとその推移的依存関係を確認するのに役立ちます。ライブラリのバージョン競合が起きた場合などに原因を特定しやすくなります。

コマンド実行時の便利なオプション

Gradleコマンドには、実行をカスタマイズするためのオプションがあります。例えばテストをスキップしたい場合は ./gradlew build -x test のように-xオプションでタスクを除外できます。これは一時的にテストを省略してビルドだけを確認したい場合に便利です。

複数プロジェクト構成の場合、タスク名の前にコロン付きでプロジェクトを指定できます。例：./gradlew :app:tasks、./gradlew :subproject:test。特定のサブプロジェクトだけをビルド・テストしたい場合に使用します。

また、Gradleには増分ビルド機能があり、変更のないタスクは自動的にスキップされます。これにより2回目以降のビルドが高速になりますが、確実にすべて実行したい場合は--rerun-tasksオプションを使用できます。なお、初回の./gradlew実行時はGradle本体のダウンロードで時間がかかることがありますが、これは恒常的な問題ではありません。

要点：基本コマンドはbuild（ビルド＋テスト）、run（実行）、test（テスト）、clean（削除）、tasks（一覧）です。タスクは複数指定でき、-xオプションで除外も可能です。

Gradle Wrapperでバージョンを更新する方法と注意点

Wrapperを使ったバージョン更新手順

Gradle Wrapperを使えば、システムにGradleをインストールしていなくてもプロジェクトのGradleバージョンを更新できます。更新は以下のコマンドで行います。

  1. プロジェクトのルートディレクトリに移動
  2. ./gradlew wrapper --gradle-version=<新しいバージョン> を実行
  3. 例：./gradlew wrapper --gradle-version=9.6.1
  4. 次回の./gradlew実行時に新しいバージョンが自動ダウンロードされる

このコマンドにより、gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.propertiesが更新されます。--distribution-type=binを付けるとバイナリ配布を明示的に指定できます。ダウンロードされたGradleは~/.gradle/wrapper/distsにキャッシュされ、2回目以降はキャッシュから実行されます。（出典：Gradle公式「Gradle Wrapper Basics」）

システムインストール済みGradleの更新

システムにインストールしたGradle本体を更新する場合は、インストール方法に応じたコマンドを使用します。

インストール方法 更新コマンド
SDKMAN! sdk install gradle（最新版）または sdk install gradle 9.6.1（特定版）
Homebrew brew upgrade gradle
手動インストール 新しいZIPをダウンロード・解凍し、GRADLE_HOMEを差し替え

手動インストールの場合、シンボリックリンク（例：/opt/gradle/current）を使ってGRADLE_HOMEを参照すると、バージョン切り替えが容易になります。ただし、プロジェクト単位ではWrapperを使うのが公式推奨です。システムのGradleを更新しても、既存プロジェクトはWrapperに設定されたバージョンを使い続けるためです。

更新時の注意点と互換性確認

Gradleバージョンを更新する前に、Java/JDKとの互換性を必ず確認してください。Gradle 9.x系の実行にはJDK 17以上が必要です。また、JavaのバージョンとGradleのバージョンは別物で、例えばJava 26でGradleを実行するにはGradle 9.4.0以降が必要です。Java 21で実行する場合はGradle 8.5以降が必要になります。

アップグレード前に、プロジェクトが新しいGradleバージョンで正しく動作するかテストすることを推奨します。Gradleのアップグレードガイドには非推奨化された機能や破壊的変更が記載されているため、大きなバージョンアップの場合は事前に確認しましょう。2026年8月時点の最新安定版はGradle 9.6.1です。（出典：Gradle公式「Gradle 9.6.1 Release Notes」）

要点：Wrapperの更新は「./gradlew wrapper –gradle-version=」で行います。更新前にJDK互換性とアップグレードガイドの確認が重要です。

“`