skip to content

What does running Gradle with --offline do, and what are the prerequisites for it to succeed?

level: middleimportance: must knowfreq 45%

answer

  1. no network, cache-only resolution
  2. fails fast if anything missing
  3. warm the cache online first
  4. CI: restore GRADLE_USER_HOME then --offline
  5. won't refresh dynamic/changing modules

basics

~10 s

--offline tells Gradle never to access the network during a build; it resolves everything from the dependency cache. It only succeeds if every required metadata and artifact is already cached, otherwise the build fails.

solid answer

~50 s

`--offline` forces Gradle to **resolve dependencies exclusively from the local cache** (`caches/modules-2`) and never contact any repository. It's used when you have no network, want deterministic resolution, or want to guarantee a build doesn't reach out unexpectedly. The hard prerequisite is that **everything the build needs is already in the cache** — all metadata and all artifacts for the configurations being resolved. If even one module is missing, the build fails with a resolution error rather than falling back to the network. Practically you 'warm' the cache once with a normal online build (or a CI cache restore), then run subsequent builds `--offline`. It also interacts with freshness: while offline, Gradle won't re-resolve dynamic versions or refresh changing modules — it just uses whatever the cache last resolved. `--offline` and `--refresh-dependencies` are mutually exclusive in intent (one forbids the network, the other mandates contacting it).

code

bash · 6 lines
bash
# Warm the cache once (online)
./gradlew build

# Then build with no network access at all
./gradlew test --offline
# A missing module -> resolution failure, no fallback to the repo

go deeper

for a junior

Know --offline means no network and uses the local cache only.

for a middle

Explain fail-fast on missing modules, the warm-cache prerequisite, and the no-refresh-while-offline behavior.

for a senior

Discuss CI cache restoration, plugin/classpath configurations being missing, and security/determinism motivations.

for a principal

Address air-gapped/reproducible-build governance: seeded mirrors, dependency verification, and guaranteed-offline pipelines.

## What --offline means The `--offline` flag puts Gradle into a mode where it **must not perform any network access** for dependency resolution. Every module's metadata and every artifact is served from the local **dependency cache** at `GRADLE_USER_HOME/caches/modules-2`. If the cache can satisfy the whole graph, the build runs exactly as it would online; if anything is missing, the build **fails fast** — it will not silently reach out to a repository. ## Why use it - **No / unreliable network** (on a plane, an air-gapped environment, flaky CI). - **Determinism / speed** — guarantees the build won't block on a slow repository and uses the exact already-resolved versions. - **Security posture** — prove a build cannot exfiltrate or fetch from the network. ## Prerequisites The single requirement is a **warm cache**: you must have previously resolved (online) every dependency the offline build needs, including transitive ones, for all configurations that get resolved. The usual workflow: ```bash # 1) Warm the cache once, with network ./gradlew build # 2) Subsequent builds can run with no network ./gradlew test --offline ``` On CI this is typically done by **restoring a cached GRADLE_USER_HOME** from a previous job before running `--offline`. ## Interaction with freshness While offline, Gradle does **not** re-check dynamic versions (`1.+`) or refresh changing modules (`-SNAPSHOT`); it returns whatever was last resolved and cached. So `--offline` and `--refresh-dependencies` are contradictory — the former bans the network, the latter requires it. Passing both is nonsensical. ## Gotchas - A configuration you don't normally resolve (e.g. a plugin-classpath or a rarely-run task's dependencies) can be missing from the cache and break an otherwise-fine offline build. - Plugin resolution from the Plugin Portal also needs to be cached for fully offline builds. - `--offline` does not stop **declared** repository definitions from existing; it just prevents reaching them.

  • What happens if a required dependency is not in the cache when you run --offline?
    The build fails with a dependency-resolution error. Gradle will not fall back to the network in offline mode — the missing module simply can't be resolved.
  • Can you combine --offline with --refresh-dependencies?
    It makes no sense: --refresh-dependencies requires contacting the repositories while --offline forbids any network access. They express opposite intents, so combining them is contradictory.
  • How do you make an offline build reliable on CI?
    Restore a previously populated GRADLE_USER_HOME (the dependency cache) as a CI cache layer before the offline step, ensuring every needed module/plugin was warmed by an earlier online build.

saying these in an interview costs you the question

  • Saying Gradle falls back to the network if something is missing in offline mode — it fails instead.
  • Thinking --offline disables caching — it relies entirely on the cache.
  • Forgetting that plugin resolution also needs to be cached for a fully offline build.

context

resolving links…