Gradle を使っていると、依存関係の取得で毎回ネットワークに行ってほしくない場面があります。
たとえば、移動中で通信が不安定なとき、社内ネットワークの制約で一時的に外へ出られないとき、あるいは「いま手元にあるキャッシュだけでビルドできるか」を確かめたいときです。
そんなときに使えるのが --offline オプションです。
実務では、インターネットに接続できない実行環境で Gradle を動かしたい場面でも出てきます。たとえば、あらかじめ依存関係を解決した Docker イメージを作っておき、そのイメージを使って Kubernetes Job から社内の開発環境サーバへ E2E テストを実行するようなケースです。
この記事では、Gradle の --offline が何をするのか、通常実行と何が違うのか、どんなときに失敗するのかを整理します。
この記事で分かること
- Gradle の
--offlineオプションの基本動作 --offlineを付けたときにビルドが通る条件--refresh-dependenciesとの違い- Docker イメージや Job 実行のような制約環境での考え方
- どんな場面で使うと便利か
先に結論
--offlineは、Gradle にネットワークアクセスなしで依存解決させるオプションです- すでにローカルキャッシュにある依存関係だけでビルドできる場合は通ります
- 必要な依存関係やプラグインが未キャッシュならビルドは失敗します
- 「最新を取りに行きたい」ときのオプションではなく、むしろ逆です
–offline は何をするのか
Gradle 公式ドキュメントでは、--offline は「ネットワーク資源にアクセスせずに build を動かす」ためのオプションとして説明されています。
依存関係のキャッシュに関する説明では、もう少し具体的に次のような挙動になっています。
- 依存モジュールはキャッシュから使う
- 本来なら再確認の対象になっている依存関係でも、ネットワークへ見に行かない
- 必要なモジュールがキャッシュにない場合は失敗する
実際には、次のように使います。
./gradlew build --offlineテストだけならこうです。
./gradlew test --offlineポイントは、「依存解決を完全に止める」というより、「依存解決で外部へ取りに行かないようにする」と考えると分かりやすいことです。
この記事の内容は、Gradle 公式ドキュメントの確認に加えて、2026-07-07 に手元で ./gradlew test --offline --no-daemon を使ったローカル検証でも確かめています。
通常実行との違い
通常の Gradle 実行では、ローカルキャッシュを見たうえで、必要ならリモートリポジトリも確認します。
一方で --offline を付けると、Gradle はネットワークへアクセスしません。たとえキャッシュの再確認タイミングが来ていても、その場では再取得しません。
この違いは、特に動的バージョンや changing dependencies を使っているときに効いてきます。
たとえば 1.+ のような動的バージョンや、SNAPSHOT のように更新されうる依存関係は、通常なら Gradle が一定条件で再確認します。しかし --offline では、その再確認も行いません。
つまり --offline は、「いま手元にある依存キャッシュ前提で固定して動かす」ためのスイッチです。
どんなときに便利か
1. 通信が不安定でも手元作業を進めたいとき
一度依存関係を取得済みなら、オフラインでも compile や test を継続できることがあります。
とくにノート PC での移動中や、VPN が不安定な環境では便利です。
2. キャッシュだけで再現できるかを確認したいとき
CI やチーム開発では、「たまたま今のネットワーク状態で通った」ではなく、「必要な依存が手元にそろっているか」を確認したい場面があります。
--offline を付けて通るなら、その時点では少なくとも追加ダウンロードなしで実行できています。
実際に手元検証でも、必要な plugin と dependency が入った GRADLE_USER_HOME を使った場合は、Spring Boot サンプルの test が --offline 付きで成功しました。
3. 不要なリモートアクセスを避けたいとき
依存の再確認自体を抑えたいときにも有効です。
ただし、これは「ビルドを速くする万能オプション」という意味ではありません。依存キャッシュが未整備なら、むしろ失敗しやすくなります。
4. ネットワーク制約のある実行環境で Gradle を動かしたいとき
これは実務ではかなり分かりやすい使いどころです。
たとえば、Kubernetes Job で E2E テストを実行したいが、その Job が動く実行環境はインターネットへ出られない、ということがあります。このとき、Job の中で毎回 dependency を取りに行く構成だと失敗しやすくなります。
そこで、先に依存関係を解決した状態を Docker イメージへ含めておき、Job 実行時は --offline で Gradle を動かす、という構成が取りやすいです。
イメージとしては次のような流れです。
flowchart LR
Build["CI or image build"] --> Resolve["Gradle dependencies resolved"]
Resolve --> Package["Package cache and test code into Docker image"]
Package --> Job["Kubernetes Job starts in restricted network"]
Job --> Offline["Run Gradle with --offline"]
Offline --> E2E["Execute E2E tests against internal dev server"]この使い方では、--offline 自体が主役というより、「事前に必要なものをイメージへ閉じ込める」設計とセットで効いてきます。
逆に言うと、イメージ作成時点で必要な plugin や dependency がそろっていなければ、Job 実行時に --offline を付けても解決できません。
失敗しやすいケース
--offline は便利ですが、次のケースでは普通に失敗します。
依存関係がまだ落ちてきていない
初回ビルドや、新しいライブラリを追加した直後は、必要な artifact や metadata がローカルにないことがあります。
この状態で --offline を付けると、Gradle は取りに行けないので失敗します。
Gradle plugin が未取得
依存ライブラリだけでなく、利用している plugin の解決にもキャッシュが必要です。
たとえば初めて使う plugin を追加した直後は、まずオンラインで一度解決させる必要があります。
手元検証でも、Spring Boot plugin を使うサンプルに対して空の GRADLE_USER_HOME で ./gradlew test --offline --no-daemon を実行すると、plugin 解決の段階で失敗しました。
キャッシュを前提にしすぎる
ローカルでは通るのに、別マシンや新しい開発環境では通らない、ということも起きます。
--offline は「ローカルキャッシュが育っていること」を前提にしたオプションです。セットアップ直後の環境に向くものではありません。
また、plugin までは解決できても dependency cache が足りなければ、No cached version ... available for offline mode. のような形で失敗します。
./gradlew の wrapper 取得とは別で考える
ここは少しややこしいポイントです。
少なくとも 2026-07-07 の手元検証では、空の GRADLE_USER_HOME で ./gradlew test --offline --no-daemon を実行したとき、先に Gradle Wrapper が gradle-9.5.1-bin.zip を取得し、そのあとで plugin 解決が offline mode で失敗しました。
つまり、--offline を付けたからといって、./gradlew の bootstrap まで全部止まるとは限りません。
記事としては、「--offline は Gradle build 本体の依存解決に効くオプション」と理解しておく方が混乱しにくいです。
–refresh-dependencies との違い
名前の雰囲気が逆なので、--offline と --refresh-dependencies はセットで覚えると分かりやすいです。
まずは表で見ると整理しやすいです。
たとえばこんな使い分けになります。
- いまあるキャッシュだけでビルドしたい
./gradlew build --offline
- 依存関係の状態を取り直したい
./gradlew build --refresh-dependencies
なお、--refresh-dependencies は「必ず全部を再ダウンロードする」意味ではありません。Gradle 公式ドキュメントでも、必要な確認は行うが、変化がなければ不要な再ダウンロードまではしないと説明されています。
実務での考え方
個人的には、--offline は常用オプションというより、状況を切り分けるためのオプションとして使うのが分かりやすいです。
たとえば次のような問いに向いています。
- これはネットワーク依存の失敗なのか
- 依存関係はすでに手元にあるのか
- その build はオフライン前提でも回るのか
一方で、CI で常に --offline を付ければよいとは限りません。CI は毎回クリーンな環境で動くことも多く、キャッシュ戦略を別途考えたほうが本筋です。
ただ、Docker イメージを使って閉じた環境へ持ち込む運用では話が少し変わります。その場合は、--offline は単なる切り分け用ではなく、「イメージ作成時に依存解決を終わらせ、実行時には外へ出ない」という実行モデルの一部になります。
とくに、Kubernetes Job から社内の開発環境サーバへ E2E テストを打ちに行くような構成では、この考え方はかなり自然です。Job 実行時には Maven Central や Plugin Portal に出られなくても、社内サーバへは到達できればよいからです。
手元検証で確認できたこと
今回のローカル検証では、GRADLE_USER_HOME の状態によって挙動がはっきり変わりました。
- plugin と dependency の cache がある状態では、
./gradlew test --offline --no-daemonは成功した - 空の
GRADLE_USER_HOMEでは、Spring Boot plugin の解決で失敗した - wrapper distribution だけあって dependency cache がない状態では、
No cached version ... available for offline mode.で失敗した
この結果からも、--offline は「ネットワークに行かない魔法の build オプション」ではなく、「いま手元にある cache を前提に build するオプション」と捉えるのが実務ではしっくりきます。
まとめ
Gradle の --offline は、「依存関係をキャッシュからだけ使い、ネットワークへ行かずに build する」ためのオプションです。
すでに必要な依存関係や plugin がローカルにそろっていれば便利ですが、未取得のものがあると失敗します。
そのため、「最新版を取りたい」ときではなく、「いまあるキャッシュだけで動かしたい」「ネットワークに依存したくない」という場面で使うオプションとして理解しておくと扱いやすいです。