skip to content

What does the `--offline` flag do, and how does it interact with Gradle's dependency cache?

level: middleimportance: should knowfreq 50%

answer

  1. no network access at all
  2. resolve from local cache only
  3. fails if artifact not cached
  4. skips dynamic/changing version checks
  5. opposite of --refresh-dependencies

basics

~10 s

--offline tells Gradle never to access the network during the build. It resolves dependencies purely from the local dependency cache and fails if a required artifact or metadata isn't already cached.

solid answer

~40 s

`--offline` forces Gradle to run without any network access: all dependency resolution must be satisfied from the **local dependency cache** under the Gradle user home. Gradle will not contact remote repositories, will not re-check for changing/dynamic version updates, and will fail the build if a needed artifact or its metadata isn't already cached. It's useful for reproducible/air-gapped builds, working on a plane, or avoiding flaky-registry delays. The key interaction: it changes *where* dependencies come from (cache only) but doesn't disable caching — it just forbids the network fallback. It pairs with `--refresh-dependencies` as the opposite intent: `--offline` says 'cache only, never network'; `--refresh-dependencies` says 'ignore cached metadata, re-fetch from network'.

code

bash · 5 lines
bash
# Build using only already-cached dependencies, no network
gradle build --offline

# Opposite intent: re-fetch metadata from remote repos
gradle build --refresh-dependencies

go deeper

for a junior

Knows it means 'no network — use cached dependencies' and fails if something isn't cached.

for a middle

Explains it skips dynamic/changing version checks and contrasts it with --refresh-dependencies.

for a senior

Discusses air-gapped/reproducible builds and the empty-cache caveat for first builds; situates it as dependency-resolution-only.

for a principal

Frames offline/air-gapped strategy (pre-seeded caches, internal mirrors, dependency locking) for secure or disconnected CI environments.

## Gradle's dependency cache Gradle stores resolved dependency metadata and artifacts in a **local dependency cache** (in the Gradle user home, default `~/.gradle/caches/modules-2`). On a normal build, Gradle consults this cache and only hits remote repositories when something is missing or when checking whether a **dynamic** version (`1.+`) or **changing** module (a `-SNAPSHOT`) has a newer version. ## What `--offline` enforces ```bash gradle build --offline ``` `--offline` makes Gradle **never touch the network**. Concretely: - Dependency resolution is satisfied **only** from the local cache. - Gradle does **not** check remote repositories for updates to dynamic/changing versions — it uses whatever is cached. - If a required artifact or its metadata is **not** cached, the build **fails** with an unresolved-dependency error (it won't go fetch it). ## Why use it - **Reproducibility / air-gapped** environments where the network is unavailable or untrusted. - **Speed/stability**: skip remote checks for changing modules and avoid hangs on slow or down registries. - Working **disconnected** (travel, restricted networks). ## Relationship to other dependency flags - `--offline` is the **opposite intent** of `--refresh-dependencies`. The latter ignores cached metadata and re-fetches from the network to pick up updates; `--offline` forbids the network entirely. - It is unrelated to `--rerun-tasks` (task execution) — `--offline` only governs **dependency resolution / network access**. ## Caveat A first-ever build of a project usually **can't** run offline because nothing is cached yet — you need at least one online resolution to populate the cache, after which offline builds work. Plugins resolved from a plugin repository are subject to the same rule.

  • Can you run a brand-new project's first build with `--offline`?
    Usually no — the dependency cache is empty, so resolution fails. You need at least one online build to populate the cache; afterwards offline builds work.
  • How does `--offline` treat a `-SNAPSHOT` (changing) dependency?
    It uses the already-cached version and does NOT check the remote for a newer snapshot, since that check requires network access.
  • What's the relationship between `--offline` and `--refresh-dependencies`?
    Opposite intents: `--offline` forbids the network and uses the cache as-is; `--refresh-dependencies` ignores cached metadata and re-fetches from remote repositories to get updates.

saying these in an interview costs you the question

  • Saying `--offline` disables caching (it relies on the cache).
  • Claiming it will download missing artifacts 'when it can' — it never touches the network.
  • Confusing it with `--rerun-tasks` (task execution, not dependency resolution).

context

resolving links…