Javaのプロジェクトを開いたら、見慣れない gradlew や build.gradle.kts が並んでいて、何から触ればいいのか固まった経験はないでしょうか。
私も最初は完全にそうでした。ビルドが通らないまま手が止まる、あの絶望感です。
Gradle（グレイドル）とは、コンパイルからテスト、JARの作成までを自動化するビルドツールです。
押さえるのは「./gradlew で動かす」「build.gradle を読める」「依存とタスクの考え方を知る」の3つだけです。
私は普段Spring Bootの開発でGradleを毎日使っていて、過去にはMavenのXML地獄にも住んでいました。
この記事でわかること
- Gradleの正体と、Build・Project・Task・Pluginの4つの基本概念
- なぜ
./gradlew（Wrapper）を使うのが正解なのか - build.gradleの書き方と、依存スコープ・タスク・キャッシュの仕組み
- GradleとMavenをどう選び分けるかの判断軸
PARTS LIST ／目次
Gradleとは？ビルドを自動化するツールの基本
Gradleとは、ビルド・テスト・デプロイを自動化するビルドツールです。GroovyまたはKotlinで書かれたビルドスクリプトに従って動きます。
Javaの世界ではMavenやAntの後発として登場し、今ではAndroidの公式ビルドツールでもあります。
この記事は2026年9月時点のGradle 9系をもとにしています。
「ビルドツール」と言われてもピンと来ないかもしれません。
ざっくり言うと、ソースコードをコンパイルして、テストを走らせて、配布用のファイルにまとめる、という一連の作業を自動でやってくれる係です。
手作業でやると地獄ですが、Gradleなら ./gradlew build の一発で終わります。
Gradleが解決してくれる課題
Gradleが片付けてくれる悩みは、主に「依存ライブラリの管理」と「ビルド手順の標準化」です。
必要なライブラリのバージョンを書くだけで、Gradleが自動でダウンロードしてくれます。手元でJARを集めて回る必要はありません。
さらにビルド手順がスクリプトとして残るので、チームの誰がやっても同じ結果になります。
「自分のPCでは動くのに」という、あの定番のトラブルを減らせるわけです。
Build・Project・Task・Pluginの4つの基本概念
Gradleを理解する近道は、登場人物を覚えることです。Build・Project・Task・Pluginの4つに、関連する用語のBuild ScriptとDependencyを加えて表にまとめました。表の用語を押さえれば、残りは応用です。
関係を一言でまとめると、こうです。
BuildはProjectを束ね、ProjectはTaskを持ち、PluginがそのProjectに便利なTaskを足してくれます。
そしてDependencyはProjectが外から借りてくる部品、というイメージです。
gradle initで新規プロジェクトを作る手順
新規プロジェクトを作るときは、gradle init コマンドを使います。
空のディレクトリで実行すると、対話形式でいくつか質問されます。主に聞かれるのは、プロジェクトの種類（アプリケーション／ライブラリ等）・言語・ビルドスクリプトの形式（Kotlin/Groovy）です。ほかにJavaのバージョン、プロジェクト名、テストフレームワークなども聞かれます。
mkdir my-app && cd my-app
gradle init --type java-application実行が完了すると、build.gradle(.kts)・settings.gradle(.kts)・gradlew 一式が自動生成されます。
続けて ./gradlew build を実行すれば、その場でビルドが通ることを確認できます。
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 9.7
# Wrapper経由でビルド
./gradlew build # Unix / macOS / Linux
gradlew.bat build # Windowsgradle build./gradlew buildgradlewと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 "4.1.1" // 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:4.1.1"
compileOnly "org.projectlombok:lombok:1.18.36"
annotationProcessor "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 "4.1.1" // 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:4.1.1")
compileOnly("org.projectlombok:lombok:1.18.36")
annotationProcessor("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では、依存をまとめて1つにしたFat JAR（実行可能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つです。名前を見れば用途が想像できるよう、よく使う順に並べました。
迷いやすいcompileOnlyとimplementationの違いは、実行時にそのライブラリが必要かどうかです。
Lombokのようにコンパイル時だけ使ってバイナリには残らないものはcompileOnly、実行時にも必要な通常のライブラリはimplementationを使います。
なお、Lombokはアノテーションプロセッサとして動かすため、annotationProcessorにも同じ依存を書く必要があります。compileOnlyだけだと、@Getterなどが処理されずコンパイルエラーになります。
推移的依存とバージョン衝突の解決
推移的依存とは、依存ライブラリがさらに別のライブラリに依存することです。Gradleはこれも自動で解決します。問題はバージョンがぶつかったときです。
たとえばA→C v1.0、B→C v2.0と要求が割れた場合、どちらを使うかが争点になります。
解決のフローはシンプルです。
宣言を読み、リポジトリを順に検索し、最初に見つかったものを使い（First Wins）、ダウンロードしたJARは ~/.gradle/caches/ にキャッシュします。
次回以降はキャッシュから読むので、オフラインでもビルドできます。
困ったら ./gradlew dependencies でツリーを、./gradlew dependencyInsight --dependency <ライブラリ名> で解決の経緯を確認できます。
dependencies {
implementation("com.example:library-b") {
version { strictly("2.0") } // このバージョンに固定
exclude(group = "com.old", module = "unused-lib") // 不要な推移的依存を除外
}
}古い記事でよく見る force = true は、Gradle 8.0で削除されました（公式のアップグレードガイド）。今のGradleでは、上のように version { strictly("2.0") } でバージョンを固定します。
バージョンカタログで依存を一元管理
バージョンカタログ（libs.versions.toml）は、依存とバージョンを1か所にまとめる方法です。
Gradle 7.0以降で導入され、2026年現在は標準的な手法になっています。
バージョンの散らばりを防げて、RenovateやDependabotの自動更新とも相性が良いです。
# gradle/libs.versions.toml
[versions]
spring-boot = "4.1.1"
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 に入れておきましょう。
--scanはビルドの遅延原因を可視化できて便利です。ただし、Build Scanはビルドの情報をGradle社が管理する外部のサーバーに送って作られ、初回は利用規約への同意を求められます。業務のコードでは送信してよいかを確かめ、調査したいときだけ付けるのが無難です。
タスクの依存関係と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の最大の武器は速さです。前回のビルド結果をキャッシュし、変わった部分だけ再実行してくれます。
設定を少し足すだけで、ビルド時間が体感で大きく縮みます。ここはぜひ有効化しておきたいポイントです。
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つのフェーズで動かします。
1つ目は、settings.gradleを読むInitializationです。2つ目は、各build.gradleを評価してDAGを作るConfigurationです。最後に、タスクを実際に走らせるExecutionが続きます。
この流れを知っておくと、エラーがどの段階で起きたか見当が付きます。
注意したいのは、org.gradle.caching=trueで有効になるのはあくまでローカルマシン内でのビルドキャッシュだという点です。
チームメンバーやCI環境とキャッシュを共有するには、リモートビルドキャッシュ用のサーバーが別途必要です。Develocity（旧Gradle Enterprise）などが使えます。
GradleとMavenの違いをどう考えるか
GradleとMavenの一番の違いは、設定の書き方と速度です。MavenはXMLで、Gradleはコード（DSL）で書きます。
新しいプロジェクトでGradleが選ばれやすい理由は、記述量の少なさと、インクリメンタルビルドの速さです。
とはいえ、Mavenが劣っているわけではありません。XMLは構造が決まっていて読みやすく、学習コストも緩やかです。
プロジェクトの性質やチームの慣れで選べばいいと考えています。
既存プロジェクトをMavenからGradleへ移行する場合は注意が必要です。
pom.xmlの依存をそのままbuild.gradleへ手動で書き写すと、依存関係の解決順序の違いにハマりやすいためです。
いきなり全面書き換えをするのはおすすめしません。
gradle initのMaven変換機能で自動生成した内容と手元のpom.xmlを見比べ、差分を潰していく進め方のほうが、手戻りを抑えやすくなります。
設定言語・速度・Android対応の比較
両者の違いを表でまとめます。決め手になりやすいのは、ビルド速度・Android対応・Wrapperの有無あたりです。
新規プロジェクトでKotlin DSLを選ぶ理由
2026年現在、新規プロジェクトではKotlin DSLが推奨されています。最大の理由はIDE補完の強さと型安全性です。
Groovyは動的型付けでサクッと書けますが、補完が弱く、書き間違いに気づきにくい弱点があります。
正直なところ、Kotlin DSLは記述量がやや増え、学習曲線も少し急です。
それでも新規でKotlin DSLが勧められるのは、長く保守するほど補完と型チェックの恩恵が効いてくるからです。短期の使い捨てスクリプトならGroovyでも構いません。
Gradleの基本に関するよくある質問（FAQ）
最後に、Gradleを学び始めた人からよく出る質問をまとめます。短く答えるので、つまずいたときの早見表として使ってください。
Q1. gradleコマンドと./gradlewはどちらを使う？
A1. ./gradlew を使います。Wrapper経由なら、プロジェクトで固定したバージョンで動くからです。gradle コマンドはマシンごとにバージョンが違い、再現性に問題が出ます。普段のビルドは ./gradlew 一択で大丈夫です。
Q2. build.gradleとbuild.gradle.ktsの違いは？
A2. 書く言語の違いです。build.gradle はGroovy、build.gradle.kts はKotlinで書きます。やれることはほぼ同じですが、Kotlin DSLは補完と型チェックが強力です。2026年現在の新規プロジェクトではKotlin DSLが推奨されています。
Q3. implementationとapiの使い分けは？
A3. 基本は implementation を使います。依存が外部に公開されず、ビルドも速くなるからです。api は、その依存を使う側にも見せたいマルチモジュールのライブラリ層でのみ使います。迷ったら implementation で問題ありません。
Q4. implementationとcompileOnlyの違いは？
A4. 違いは、実行時にそのライブラリが必要かどうかです。implementation はコンパイル時と実行時の両方で使い、compileOnly はコンパイル時だけ使います。Lombokのようにコンパイル後は不要なものは compileOnly、実行時にも必要な通常のライブラリは implementation にします。
Q5. 依存のバージョンを変えたら何をすればいい？
A5. build.gradleを保存して ./gradlew build を実行するだけです。Gradleが新しいバージョンを自動でダウンロードします。挙動がおかしいときは ./gradlew --refresh-dependencies で依存のキャッシュを更新し、./gradlew clean でビルド成果物を消して作り直してみてください。
Q6. gradlewはGitにコミットすべき？
A6. はい、コミットします。gradlew・gradlew.bat・gradle/wrapper/ 一式はバージョン管理に含めるのが正解です。Wrapper一式を共有すると、チーム全員が同じバージョンのGradleでビルドできます。build/ ディレクトリだけは .gitignore に入れます。
まとめ：Gradleの基本はWrapperと4概念から
Gradleの基本を駆け足で総ざらいしてきました。最初は呪文に見えた build.gradle.kts も、骨組みが分かれば怖くありません。
今日の要点を最後に圧縮しておきます。
- 普段のビルドは
./gradlew（Wrapper）を使う。再現性が段違い - Build・Project・Task・Pluginの4概念を押さえれば設定が読める
- 依存はスコープで使い分け、迷ったら implementation でOK
- タスクはDAGで自動的に順序が決まる。clean だけは別枠
- 新規ならKotlin DSL + バージョンカタログが2026年の定番
まずは手元のプロジェクトで ./gradlew tasks を叩いて、どんなタスクがあるか眺めてみてください。そこから自分のビルドが見えてきます。
| REV. | DATE | 内容 |
|---|---|---|
| 4 | 2026-10-16 | 図解を描き直し（図面のデザインにそろえた） |
| 3 | 2026-10-04 | 記載内容の事実確認と修正 |
| 2 | 2026-09-02 | 2026年9月時点の情報で全体を見直し（古い記述を9件更新） |
| 1 | 2026-06-07 | 初版 |