Gradleの基本を総まとめ｜入門から実践まで網羅

Javaのプロジェクトをクローンして開いた瞬間、見慣れない gradlew や build.gradle.kts が並んでいて、「これ何から触ればいいの……」と固まった経験はないでしょうか。私も最初は完全にそうでした。ビルドが通らないだけで半日溶ける、あの絶望感です。

Gradleは奥が深いツールですが、基本の骨組みは驚くほどシンプルです。要は「Wrapperで動かす」「3つの概念を押さえる」「依存とタスクの考え方を知る」だけで、日常のビルドはほぼ困らなくなります。

私は普段Spring Bootの開発でGradleを毎日使っていて、過去にはMavenのXML地獄にも住んでいました。その経験をふまえて、Gradleの基本を1記事で総ざらいします。読み終わるころには ./gradlew build が何をしているか、自分の言葉で説明できるはずです。

Gradleとは？ビルドを自動化するツールの基本

Gradleとは、ビルド・テスト・デプロイを自動化するビルドツールです。GroovyまたはKotlinで書かれたビルドスクリプトに従って動きます。Javaの世界ではMavenやAntの後発として登場し、今ではAndroidの公式ビルドツールでもあります。2026年5月時点の最新バージョンは9.5.0です。

「ビルドツール」と言われてもピンと来ないかもしれません。ざっくり言うと、ソースコードをコンパイルして、テストを走らせて、配布用のファイルにまとめる、という一連の作業を自動でやってくれる係です。手作業でやると地獄ですが、Gradleなら ./gradlew build の一発で終わります。

Gradleが解決してくれる課題

Gradleが片付けてくれる悩みは、主に「依存ライブラリの管理」と「ビルド手順の標準化」です。必要なライブラリのバージョンを書くだけで、Gradleが自動でダウンロードしてくれます。手元でJARを集めて回る必要はありません。

さらにビルド手順がスクリプトとして残るので、チームの誰がやっても同じ結果になります。「自分のPCでは動くのに」という、あの定番のトラブルを減らせるわけです。

Build・Project・Task・Pluginの4つの基本概念

Gradleを理解する近道は、登場人物を覚えることです。基本となる用語は次のとおりです。ここさえ押さえれば、あとは応用でしかありません。

関係を一言でまとめると、こうです。BuildはProjectを束ね、ProjectはTaskを持ち、PluginがそのProjectに便利なTaskを足してくれます。そしてDependencyはProjectが外から借りてくる部品、というイメージです。

Gradleプロジェクトの標準ディレクトリ構成

Gradleプロジェクトには、お決まりのフォルダ構成があります。中でも gradlew と gradlew.bat があれば、それはGradleプロジェクトの証です。最初はこの2つを目印にすると迷いません。

project/
├── gradle/                  # Wrapper JAR等の格納ディレクトリ
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew                  # Wrapperスクリプト（Unix用）
├── gradlew.bat              # Wrapperスクリプト（Windows用）
├── settings.gradle(.kts)    # ルートプロジェクト名・サブプロジェクト定義
├── build.gradle(.kts)       # ルートプロジェクトのビルドスクリプト
├── subproject-a/
│   ├── build.gradle(.kts)
│   └── src/
└── subproject-b/
    ├── build.gradle(.kts)
    └── src/

Gradle Wrapper（gradlew）が最重要な理由

Gradleで一番大事なものを1つだけ挙げるなら、Wrapper（gradlew）です。Wrapperを使うと、PCにインストール済みのGradleバージョンに左右されず、プロジェクトで固定したバージョンでビルドできます。結論から言うと、普段のビルドは gradle コマンドではなく ./gradlew を使うのが正解です。

理由はシンプルで、再現性が段違いだからです。WrapperはGitにコミットして共有するので、誰がクローンしても同じバージョンのGradleが自動でダウンロードされます。CI/CDでもバージョンが一致し、「手元で動かない」を根本から防げます。Gradle未インストールの環境でもビルドできるのが地味に効きます。

# Wrapperの生成（Gradleがインストールされていれば）
gradle wrapper --gradle-version 8.12
# Wrapper経由でビルド
./gradlew build          # Unix / macOS / Linux
gradlew.bat build        # Windows

gradlewとgradlew.batの違い

gradlew と gradlew.bat は、中身は違うけれど機能はまったく同じです。OSが違うだけで、やることは一緒だと考えてください。

どちらも gradle-wrapper.jar を起動し、gradle-wrapper.properties に書かれたバージョンのGradleをダウンロードしてビルドを実行します。両方ともバージョン管理にコミットし、.gitignore には入れません。WindowsでもGit BashやWSLなら ./gradlew が使えます。

Wrapper・Wrapperタスク・ローカルインストールの使い分け

Gradleを動かす方法は3つあります。混乱しやすいので、表で一度に整理します。結論は「普段はWrapper、初期化のときだけWrapperタスク、ローカルインストールは基本不要」です。

Wrapperタスクは新規プロジェクトを作るとき1回だけ実行すれば十分です。あとは ./gradlew で事足ります。なお gradle init でプロジェクトを生成すると、Wrapperファイルも自動で作られます。

build.gradleの基本的な書き方

build.gradle(.kts)は、プラグイン・依存関係・タスクを定義する設定ファイルです。Gradleの心臓部と言ってもいいです。ここに「何を使うか」「どこから取ってくるか」を宣言すると、Gradleがその通りに動いてくれます。

書き方には2系統あります。Groovyで書く build.gradle と、Kotlinで書く build.gradle.kts です。やりたいことは同じなので、まずは雰囲気をつかんでください。

Groovy DSLとKotlin DSLの2種類

同じ設定をGroovy DSLとKotlin DSLで書き比べてみます。まずGroovy DSL版です。シングルクォートとスペース区切りが特徴です。

plugins {
    id "java"                                          // コンパイル・テスト・JAR作成のTaskを追加
    id "org.springframework.boot" version "3.4.0"       // bootJar/bootRun等のTaskを追加
}

group = "com.example"                                  // MavenのgroupId相当。組織の名前空間
version = "1.0.0"                                      // 成果物のバージョン。未指定だと unspecified になる

java {
    sourceCompatibility = JavaVersion.VERSION_21      // ソースコードのJavaバージョン
}

repositories {
    mavenCentral()                                    // 依存のダウンロード先（Maven Central）
}

dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:3.4.0"
    compileOnly "org.projectlombok:lombok:1.18.36"
    runtimeOnly "com.mysql:mysql-connector-j:9.1.0"
    testImplementation "org.junit.jupiter:junit-jupiter:5.11.0"
    testRuntimeOnly "org.junit.platform:junit-platform-launcher:1.11.0"
}

tasks.named("test") {                                  // 自動生成された test タスクを設定
    useJUnitPlatform()                                // JUnit5で実行するよう指定
}

次にKotlin DSL版です。関数呼び出しの形（カッコ付き）になるのが見た目の違いです。IDEの補完が強力に効くので、私は新規ならこちらを選びます。

plugins {
    java                                                       // Javaプラグイン
    id("org.springframework.boot") version "3.4.0"             // Spring Bootプラグイン
}

group = "com.example"
version = "1.0.0"

java {
    sourceCompatibility = JavaVersion.VERSION_21
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web:3.4.0")
    compileOnly("org.projectlombok:lombok:1.18.36")
    runtimeOnly("com.mysql:mysql-connector-j:9.1.0")
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.0")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher:1.11.0")
}

tasks.test {                                                   // Kotlin DSLは tasks.test が直接使える
    useJUnitPlatform()
}

plugins・repositories・dependenciesの役割

build.gradleの主役は3つのブロックです。plugins で機能を足し、repositories で取得先を決め、dependencies で使うライブラリを書きます。役割を分けて覚えると、設定ファイルが一気に読めるようになります。

• plugins：JavaプラグインやSpring BootプラグインでTaskやDSLを追加する
• repositories：mavenCentral()など、依存をダウンロードする先を指定する
• dependencies：プロジェクトが使う外部ライブラリをスコープ付きで宣言する

リポジトリはMaven Central以外も指定できます。Android向けの google() や、GitHub経由の jitpack.io、ローカルの mavenLocal() などを並べて書けます。

repositories {
    mavenCentral()                          // Maven Central
    google()                                // Google（Android向け）
    maven { url "https://jitpack.io" }      // カスタムリポジトリ
    mavenLocal()                            // ローカル ~/.m2/repository
}

JAR・WAR・Fat JARの違い

宣言するプラグインによって、できあがる成果物が変わります。代表的な3種類を押さえておくと、ビルド結果に迷いません。今の主流はSpring BootのFat JARです。

マルチプロジェクトでは settings.gradle.kts でルート名とサブプロジェクトをまとめて宣言します。サブ間の参照は project(":core") のように書きます。

// settings.gradle.kts
rootProject.name = "my-project"
include("core", "web", "admin")

// web/build.gradle.kts
dependencies {
    implementation(project(":core"))  // 同じビルド内の別プロジェクトを参照
}

依存関係のスコープと解決の仕組み

依存関係のスコープとは、そのライブラリを「いつ使うか」を指定する仕組みです。コンパイル時だけ、実行時だけ、テストだけ、といった具合に用途を分けられます。無駄な依存を持ち込まないための大事な考え方です。

スコープを正しく使い分けると、ビルドが速くなり、ライブラリの公開範囲も適切になります。最初は implementation と testImplementation の2つだけ覚えれば、ほとんどのケースで足ります。

implementation・compileOnlyなど7つのスコープ

主なスコープは次の7つです。名前を見れば用途が想像できるよう、よく使う順に並べました。

推移的依存とバージョン衝突の解決

推移的依存とは、依存ライブラリがさらに別のライブラリに依存することです。Gradleはこれも自動で解決します。問題はバージョンがぶつかったときです。たとえばA→C v1.0、B→C v2.0と要求が割れた場合、どちらを使うかが争点になります。

解決のフローはシンプルです。宣言を読み、リポジトリを順に検索し、最初に見つかったものを使い（First Wins）、ダウンロードしたJARは ~/.gradle/caches/ にキャッシュします。次回以降はキャッシュから読むので、オフラインでもビルドできます。困ったら ./gradlew dependencies でツリーを、./gradlew dependencyInsight で解決の経緯を確認できます。

dependencies {
    implementation("com.example:library-b:2.0") {
        force = true                                       // このバージョンを強制
        exclude(group = "com.old", module = "unused-lib")   // 不要な推移的依存を除外
    }
}

バージョンカタログで依存を一元管理

バージョンカタログ（libs.versions.toml）は、依存とバージョンを1か所にまとめる方法です。Gradle 7.0以降で導入され、2026年現在は標準的な手法になっています。バージョンの散らばりを防げて、RenovateやDependabotの自動更新とも相性が良いです。

# gradle/libs.versions.toml
[versions]
spring-boot = "3.4.0"
junit = "5.11.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

build.gradle.ktsからは libs.spring.boot.starter.web のように参照します。IntelliJが補完してくれるので、タイプミスも減ります。マルチモジュールでも全サブプロジェクトで同じバージョンが保証される点が強力です。

よく使うGradleコマンドとタスク

Gradleの操作は、すべて ./gradlew <タスク名> の形で実行します。タスクは作業の単位なので、「やりたいこと＝タスク名」と覚えると直感的です。まずは定番のタスクから押さえましょう。

build・clean・testなど主要タスク一覧

日常で触るタスクは限られています。実務で最も多用するのは ./gradlew clean build です。下の表をブックマークしておけば、まず困りません。

オプションも覚えておくと便利です。テストを飛ばす -x test、デバッグ用の --stacktrace、ビルド診断を可視化する --scan あたりは出番が多いです。成果物は build/libs/ や build/distributions/ に生成されます。build/ は .gitignore に入れておきましょう。

タスクの依存関係とDAGによる実行順序

Gradleはタスクを dependsOn で組んだDAG（非循環有向グラフ）に従って実行します。大事なのは、ファイルに書いた順番は関係ない点です。Gradleが依存を解析して最適な順序を決めてくれます。

たとえば ./gradlew build は、コンパイル→リソース処理→JAR作成→テスト→checkという流れで自動的に並びます。依存のないタスクは並列実行も可能です。順序の指定方法は次の4つを押さえれば十分です。

ちなみに clean は依存関係の外にいます。だから clean build と明示しないと、cleanはbuildの前に走りません。実行順だけ確認したいときは ./gradlew build --dry-run が便利です。

カスタムタスクの定義方法

プラグインが用意するタスク以外に、自分でタスクを作れます。推奨は tasks.register です。必要なときだけ生成されるので、無駄がありません。tasks.create は常に生成されるため、registerを使いましょう。

// build.gradle.kts
tasks.register("hello") {
    doLast {
        println("Hello, Gradle!")
    }
}

// ファイルコピー専用のCopyタイプを使う例
tasks.register<Copy>("copyConfig") {
    from("src/config")
    into("build/config")
}

タスクには型（Type）があります。汎用の DefaultTask、ファイルコピーの Copy、削除の Delete、コマンド実行の Exec などです。登録したタスクは ./gradlew tasks で一覧確認できます。

ビルドを速くするキャッシュと設定

Gradleの最大の武器は速さです。前回のビルド結果をキャッシュし、変わった部分だけ再実行してくれます。設定を少し足すだけで、ビルド時間が体感で大きく縮みます。ここはぜひ有効化しておきたいポイントです。

gradle.propertiesでの環境設定

gradle.propertiesは、プロジェクトルートに置く設定ファイルです。JVMオプションや並列ビルドの有無などを書けます。メモリ不足でビルドが落ちるときは、org.gradle.jvmargs でヒープを増やすと直ることが多いです。

# JVMオプション（Gradleデーモンのメモリ設定）
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m

# デーモンの有効/無効（デフォルトは有効）
org.gradle.daemon=true

# 並列ビルドの有効化（マルチモジュール）
org.gradle.parallel=true

# ビルドキャッシュの有効化
org.gradle.caching=true

インクリメンタルビルドとビルドキャッシュ

キャッシュには2種類あります。デフォルトで効くインクリメンタルビルドと、マシン間で共有できるビルドキャッシュです。役割が違うので、表で整理します。

参考までに、Gradleはビルドを3つのフェーズで動かします。settings.gradleを読むInitialization、各build.gradleを評価してDAGを作るConfiguration、タスクを実際に走らせるExecutionの順です。この流れを知っておくと、エラーがどの段階で起きたか見当が付きます。

GradleとMavenの違いをどう考えるか

GradleとMavenの一番の違いは、設定の書き方と速度です。MavenはXMLで、Gradleはコード（DSL）で書きます。私は両方使ってきましたが、今はGradleに落ち着いています。理由は記述量の少なさと、インクリメンタルビルドの速さです。

とはいえ、Mavenが劣っているわけではありません。XMLは構造が決まっていて読みやすく、学習コストも緩やかです。プロジェクトの性質やチームの慣れで選べばいいと考えています。

設定言語・速度・Android対応の比較

両者の違いを表でまとめます。決め手になりやすいのは、ビルド速度・Android対応・Wrapperの有無あたりです。

新規プロジェクトでKotlin DSLを選ぶ理由

2026年現在、新規プロジェクトではKotlin DSLが推奨されています。最大の理由はIDE補完の強さと型安全性です。Groovyは動的型付けでサクッと書けますが、補完が弱く、書き間違いに気づきにくい弱点があります。

正直なところ、Kotlin DSLは記述量がやや増え、学習曲線も少し急です。それでも私が新規で選ぶのは、長く保守するほど補完と型チェックの恩恵が効いてくるからです。短期の使い捨てスクリプトならGroovyでも構いません。

Gradleの基本に関するよくある質問（FAQ）

最後に、Gradleを学び始めた人からよく出る質問をまとめます。短く答えるので、つまずいたときの早見表として使ってください。

gradleコマンドと./gradlewはどちらを使う？

./gradlew を使います。Wrapper経由なら、プロジェクトで固定したバージョンで動くからです。gradle コマンドはマシンごとにバージョンが違い、再現性に問題が出ます。普段のビルドは ./gradlew 一択で大丈夫です。

build.gradleとbuild.gradle.ktsの違いは？

書く言語の違いです。build.gradle はGroovy、build.gradle.kts はKotlinで書きます。やれることはほぼ同じですが、Kotlin DSLは補完と型チェックが強力です。2026年現在の新規プロジェクトではKotlin DSLが推奨されています。

implementationとapiの使い分けは？

基本は implementation を使います。依存が外部に公開されず、ビルドも速くなるからです。api は、その依存を使う側にも見せたいマルチモジュールのライブラリ層でのみ使います。迷ったら implementation で問題ありません。

依存のバージョンを変えたら何をすればいい？

build.gradleを保存して ./gradlew build を実行するだけです。Gradleが新しいバージョンを自動でダウンロードします。挙動がおかしいときは ./gradlew --refresh-dependencies や ./gradlew clean でキャッシュを更新してみてください。

gradlewはGitにコミットすべき？

はい、コミットします。gradlew・gradlew.bat・gradle/wrapper/ 一式はバージョン管理に含めるのが正解です。これらを共有することで、チーム全員が同じバージョンのGradleでビルドできます。build/ ディレクトリだけは .gitignore に入れます。

まとめ：Gradleの基本はWrapperと3概念から

Gradleの基本を駆け足で総ざらいしてきました。最初は呪文に見えた build.gradle.kts も、骨組みが分かれば怖くありません。今日の要点を最後に圧縮しておきます。

• 普段のビルドは ./gradlew（Wrapper）を使う。再現性が段違い
• Build・Project・Task・Pluginの4概念を押さえれば設定が読める
• 依存はスコープで使い分け、迷ったら implementation でOK
• タスクはDAGで自動的に順序が決まる。clean だけは別枠
• 新規ならKotlin DSL + バージョンカタログが2026年の定番

私自身、Mavenから移ってきた身として、Gradleの「書く量が少なくて速い」感覚にはいまだに助けられています。まずは手元のプロジェクトで ./gradlew tasks を叩いて、どんなタスクがあるか眺めてみてください。そこから自分のビルドが見えてきます。