Gradle Wrapper（gradlew）とは？役割と仕組みを解説

Gradle Wrapperの基本的な役割

Gradle Wrapperとは、プロジェクトごとに使用するGradleバージョンを固定し、自動的にダウンロードして実行する仕組みです。開発者が各自でGradleをインストールする必要がなく、プロジェクトに含まれるWrapperファイルを使うだけで、全員が同じバージョンでビルドできます。これにより、「手元では動くのにCIでは失敗する」といったバージョン差異による問題を防げます。

Gradle公式ドキュメントでは、常にWrapperを使ったビルド実行を推奨しています。インストール済みのgradleコマンドではなく、プロジェクトに含まれるgradlewを実行するのが基本です。（出典：Gradle「Gradle Wrapper Basics」）

Wrapperを構成する4つのファイル

Wrapperは以下のファイルで構成されます。これらはすべてバージョン管理システム（Git等）にコミットすることが公式の想定です。

ファイル 役割
gradlew Linux/macOS用の実行スクリプト
gradlew.bat Windows用の実行スクリプト
gradle/wrapper/gradle-wrapper.jar Gradleディストリビューションのダウンロードを担う小さなJAR
gradle/wrapper/gradle-wrapper.properties ダウンロード先URLやバージョンなどの設定ファイル

これらのファイルは手動で編集してはいけません。変更する場合は後述するwrapperタスクを使用します。ダウンロードされたGradleは~/.gradle/wrapper/distsにキャッシュされ、2回目以降は再利用されます。（出典：Gradle「Gradle Wrapper Documentation」）

初回実行時の動作の仕組み

./gradlew buildを初めて実行すると、Wrapperはgradle-wrapper.propertiesに記載されたdistributionUrlからGradleディストリビューションをダウンロードします。ダウンロード後はローカルに展開され、以降はキャッシュが再利用されるため、毎回ダウンロードが発生するわけではありません。

この仕組みにより、Gradle本体を手動インストールしていない環境でも、プロジェクトをクローンしてすぐにビルドを開始できます。CI環境や新しい開発メンバーの環境構築コストを大幅に削減できる点がWrapperの最大の利点です。なお、初回実行時のみダウンロードに時間がかかる点には注意が必要です。（出典：Gradle「Gradle Wrapper Basics」）

gradlewコマンド一覧：ビルド・テスト・依存関係確認など

ビルド・テスト関連の基本コマンド

Javaプロジェクトで日常的に使用する主要コマンドは以下の通りです。実行は./gradlew <タスク名>の形式で、Windowsではgradlew.batを使用します。

コマンド 実行内容
./gradlew build コンパイル、テスト、JAR作成まで一通り実行
./gradlew test テストのみを実行
./gradlew clean buildディレクトリの内容を削除
./gradlew run アプリケーションを実行（applicationプラグイン適用時）
./gradlew compileJava main Javaソースのみをコンパイル
./gradlew jar JARファイルを作成

複数のタスクをスペース区切りで指定することも可能です。例えば./gradlew clean buildと実行すると、cleanが先に実行されてからbuildが行われます。（出典：Gradle「Gradle Wrapper Documentation」）

依存関係・プロジェクト情報の確認コマンド

プロジェクトの依存関係や全体像を把握するためのコマンドも充実しています。トラブルシューティング時に特に役立ちます。

  • ./gradlew tasks：実行可能なタスク一覧をグループ分けして表示
  • ./gradlew tasks --all：内部タスクを含む全タスクを表示
  • ./gradlew dependencies：依存関係を構成別にツリー表示
  • ./gradlew projects：サブプロジェクトの一覧を階層表示
  • ./gradlew properties：プロジェクトのプロパティ一覧を表示
  • ./gradlew help --task <タスク名>：特定タスクの詳細情報を表示

特定の依存関係がどの経路で入ってきたかを調べるにはdependencyInsightタスクが有効です。依存関係の競合や予期しないライブラリの混入を調査する際に活用できます。（出典：Gradle「Gradle Wrapper Documentation」）

実行制御・ログ関連のオプション

ビルドの実行方法を制御するオプションも重要です。以下のオプションは日常的に使用する頻度が高いものです。

オプション 効果
--offline ネットワークにアクセスせずにビルド実行
-m, --dry-run 実際には実行せず、実行されるタスクを表示
-x, --exclude-task 指定タスクを除外して実行（例：build -x test）
--continue タスクが失敗しても可能な限りビルドを継続
-i, --info 情報レベルのログを表示
-d, --debug デバッグログを表示
--rerun-tasks up-to-dateチェックを無視して全タスクを強制実行

タスク名の省略も可能で、一意に識別できる範囲で短縮できます。例えば./gradlew cheはcheckタスクを実行します。キャメルケースの略記にも対応しており、foBaはfooBarにマッチします。（出典：Gradle「Gradle Command Line Interface Reference」）

gradle wrapperの作り方とバージョン指定・アップグレード方法

Wrapperの生成方法

新規プロジェクトでWrapperを作成するには、Gradleがインストールされた環境でgradle wrapperコマンドを実行します。またはgradle init --type java-applicationを実行すると、プロジェクト初期化と同時にWrapperファイルが自動生成されます。

特定のバージョンを指定して生成する場合は、以下のように--gradle-versionオプションを使用します。

gradle wrapper --gradle-version 9.7.0
gradle wrapper --gradle-version 9 --distribution-type all

Gradle 9系では9のようにメジャー番号のみ、9.1のようにマイナー番号のみの指定も可能です。その場合、指定した範囲内の最新バージョンに解決されます。--distribution-typeはbin（ランタイムのみ、デフォルト）とall（ドキュメント・サンプル含む）から選択できます。（出典：Gradle「Gradle Wrapper Documentation」）

既存プロジェクトのアップグレード手順

既存プロジェクトのWrapperを新しいバージョンにアップグレードする手順は以下の通りです。

  1. 最新安定版へアップグレードする場合：./gradlew wrapper --gradle-version latestを実行
  2. 特定バージョンへアップグレードする場合：./gradlew wrapper --gradle-version 9.7.0を実行
  3. ./gradlew --versionでバージョンが更新されたことを確認

重要な注意点として、wrapperタスクを1回実行しただけではgradle-wrapper.propertiesのみ更新され、gradlewやgradle-wrapper.jarは古いままの場合があります。すべてのWrapperファイルを完全に最新化するには、wrapperタスクをもう1回実行する必要があります。通常、古いWrapperファイルでも新しいGradleは実行可能ですが、完全な更新を望む場合は2回実行してください。（出典：Gradle「Gradle Wrapper Documentation」）

ビルドスクリプトでのカスタマイズ

Wrapperタスクはビルドスクリプト内でカスタマイズできます。例えば、デフォルトのディストリビューションタイプをallに設定する場合、以下のように記述します。

Groovy DSL（build.gradle）の場合：

tasks.named('wrapper') {
    distributionType = Wrapper.DistributionType.ALL
}

Kotlin DSL（build.gradle.kts）の場合：

tasks.wrapper {
    distributionType = Wrapper.DistributionType.ALL
}

この設定をしておくと、以降./gradlew wrapper --gradle-version 9.7.0を実行するだけで-allディストリビューション用のdistributionUrlが生成されます。チーム全体でディストリビューションタイプを統一したい場合に有効です。なお、gradle-wrapper.propertiesの直接編集は非推奨で、公式はwrapperタスクによる更新を推奨しています。（出典：Gradle「Gradle Wrapper Documentation」）

gradlewのプロキシ設定とセキュリティ（SHA-256検証）

プロキシ環境でのWrapper利用設定

企業ネットワークなどプロキシ経由でしかインターネットに接続できない環境では、WrapperがGradleディストリビューションをダウンロードする際にプロキシ設定が必要です。Gradleのプロキシ設定は~/.gradle/gradle.propertiesにシステムプロパティとして記述します。

認証が必要なプライベートサーバーからディストリビューションをダウンロードする場合、HTTP Basic認証を利用できます。認証情報の指定方法は2通りあり、システムプロパティでsystemProp.gradle.wrapperUserとsystemProp.gradle.wrapperPasswordを設定する方法が優先されます。もう1つはdistributionUrlに認証情報を埋め込む方法ですが、これはソース管理にコミットされるため管理された環境でのみ使用すべきです。なお、HTTP Basic認証は認証情報が平文で送信されるため、HTTPS URLで使用すべきである点に注意してください。（出典：Gradle「Gradle Wrapper Documentation」）

SHA-256ハッシュによるディストリビューション検証

Wrapperは、ダウンロードしたGradleディストリビューションをSHA-256ハッシュで検証し、中間者攻撃による改ざんを防ぐ機能を備えています。設定方法は以下の2通りです。

  • gradle-wrapper.propertiesにdistributionSha256Sumプロパティを追加
  • wrapperタスク実行時に--gradle-distribution-sha256-sumオプションを指定

チェックサムがサーバーのものと一致しない場合、Gradleはビルド失敗を報告します。ただし、検証が実行されるのはディストリビューションがまだダウンロードされていない場合のみである点に注意してください。既にキャッシュ済みの場合は検証がスキップされます。公式のハッシュ値はGradleのリリースページから取得できます。（出典：Gradle「Gradle Wrapper Documentation」）

Wrapper JARの整合性検証と注意点

gradle/wrapper/gradle-wrapper.jarは実行されるバイナリファイルであるため、その信頼性確認も重要です。Gradleは公式サイトでリリースチェックサム（https://gradle.org/release-checksums/）を公開しており、Wrapper JARの整合性を検証できます。

特に注意すべき点として、Gradle 3.3から4.0.2のバージョンで生成されたWrapper JARは再現可能なビルドができなかったため、チェックサムが発行されていません。この範囲のバージョンで生成されたWrapper JARは、公式も信頼できないものとして扱うべきと記載しています。チェックサムがリリースページにない場合、milestoneやrelease candidate、nightly buildで生成された可能性があります。侵害の疑いがある場合はGradleのセキュリティチームへの報告が推奨されています。（出典：Gradle「Gradle Wrapper Documentation」）

gradlewとgradleコマンドの違いと注意点

2つのコマンドの本質的な違い

gradleとgradlewはどちらもGradleビルドを実行するコマンドですが、使用するGradleバージョンの決定方法が根本的に異なります。

項目 gradle gradlew
Gradleの入手方法 手動インストールが必要 必要に応じて自動ダウンロード
バージョン管理 環境ごとに異なる可能性 プロジェクトごとに固定
事前準備 インストールとPATH設定が必要 プロジェクトにファイルがあれば不要
実行の一貫性 環境依存 全環境で同一バージョン
公式推奨 非推奨（既存環境での補助的利用） 常に推奨

gradleコマンドは環境にインストールされたGradleを使用するため、開発者ごとにバージョンが異なる可能性があります。一方、gradlewはgradle-wrapper.propertiesに指定されたバージョンを必ず使用するため、チーム内での一貫性が保証されます。（出典：Gradle「Gradle Wrapper Basics」）

実行時の挙動の違いと注意点

gradle buildと./gradlew buildは、インストール済みGradleとWrapper指定のGradleのバージョンが異なる場合、同じタスク名でも実行結果や動作が変わる可能性があります。Gradleはバージョン間でタスクの挙動やプラグインの互換性が変更されることがあるためです。

既存プロジェクトで作業を始める際は、まず以下の点を確認してください。

  • gradlewまたはgradlew.batが存在するか
  • gradle-wrapper.propertiesに記載されたバージョンが何か
  • 使用しているJDKバージョンがそのGradleバージョンに対応しているか

Gradleの実行には2026年8月時点でJDK 17以上が必要です。Java 21でGradleを実行するにはGradle 8.5以上、Java 26で実行するにはGradle 9.4.0以上が必要という互換性の制約もあります。（出典：Gradle「Compatibility Matrix」）

Wrapperを確実に活用するためのポイント

プロジェクトでWrapperを効果的に活用するために、以下のポイントを押さえておきましょう。

  1. 常に./gradlewを使用する：インストール済みGradleが古い・新しいにかかわらず、公式推奨はWrapperでの実行です。
  2. WrapperファイルはGitにコミットする：gradle-wrapper.jarを含むすべてのWrapperファイルをバージョン管理に含めます。
  3. バージョン変更はwrapperタスクで行う：gradle-wrapper.propertiesの手動編集は避け、./gradlew wrapper --gradle-versionを使用します。
  4. ./gradlew --versionで定期的に確認する：実際に使用されているGradleバージョンを把握できます。

WrapperはGradleの公式機能であり、独立したダウンロード製品ではありません。「Wrapperはgradle wrapperタスクで生成するもの」という理解が、正しい運用の出発点です。（出典：Gradle「Gradle Wrapper Basics」）

要点：gradlewはGradle本体を自動取得してプロジェクト固有のバージョンでビルドを実行する仕組み。常にgradlewを使い、バージョン変更はwrapperタスクで行うのが公式推奨。SHA-256検証とプロキシ設定でセキュリティと環境対応も可能。