skip to content

What does the --refresh-dependencies flag do, and when would you use it?

level: middleimportance: must knowfreq 55%

answer

  1. bypass metadata TTL, re-resolve from repos
  2. for SNAPSHOT + dynamic versions
  3. checksum match → reuse bytes
  4. does NOT clear the cache
  5. alt: cacheChangingModulesFor / cacheDynamicVersionsFor

basics

~10 s

--refresh-dependencies tells Gradle to ignore cached metadata TTLs and re-check every dependency against the repositories, re-downloading metadata and any changed artifacts. Use it when a SNAPSHOT or dynamic version seems stale.

solid answer

~50 s

`--refresh-dependencies` forces Gradle to **bypass the cached metadata's freshness rules** and re-resolve every dependency by contacting the repositories again. It re-downloads module metadata and verifies artifact checksums; if the checksum differs it re-downloads the artifact, otherwise it reuses the cached bytes. It is mainly needed for **non-reproducible coordinates**: `SNAPSHOT` versions and **dynamic versions** (`1.+`, `latest.release`), whose resolved target can change upstream while Gradle's cached answer is still within its TTL (default 24h for changing modules / dynamic version lists). It does **not** clear the cache — it just refreshes it. For fixed release versions it normally has no effect because they are assumed immutable. Common uses: a CI job that must always pick up the newest snapshot, or recovering after a bad/partial download. Prefer it over deleting the whole cache, which is a far blunter and slower instrument.

code

bash · 7 lines
bash
# Force a re-check of all dependency metadata against the repos
./gradlew build --refresh-dependencies

# Equivalent build-level config (always re-check snapshots):
# configurations.all {
#   resolutionStrategy.cacheChangingModulesFor(0, "seconds")
# }

go deeper

for a junior

Know it re-checks dependencies against the repos and is for stale SNAPSHOTs.

for a middle

Explain the metadata TTL (24h default), checksum-based artifact reuse, and that it doesn't clear the cache.

for a senior

Contrast with resolutionStrategy cache settings and explain when a CLI flag vs. baked-in policy is appropriate.

for a principal

Discuss reproducibility governance: discouraging SNAPSHOT/dynamic versions in releasable builds so refresh is rarely needed at all.

## The problem it solves Gradle caches resolved **metadata** with a time-to-live so it doesn't hit the network constantly. By default it caches the resolution of **dynamic versions** (e.g. `1.+`, `latest.release`) and the metadata of **changing modules** (e.g. `-SNAPSHOT`) for **24 hours**. Within that window Gradle answers from cache. That's great for speed but means a freshly published snapshot or a new matching release won't be seen until the TTL expires. ## What --refresh-dependencies does Running `./gradlew build --refresh-dependencies`: 1. **Ignores the cached metadata TTLs** and re-fetches module metadata (POM / Gradle Module Metadata) from the configured repositories. 2. **Re-evaluates dynamic versions** against the current repository listing. 3. For each artifact, **re-checks the checksum**; if the remote checksum matches what's cached, the cached bytes are reused (no re-download), otherwise the artifact is re-downloaded. It does **not** delete the cache, and it does **not** override repository-level guarantees — fixed release versions are still treated as immutable, so the flag is essentially a no-op for them. ## When to use it - A SNAPSHOT dependency was just republished and you need the new bits now. - A dynamic version (`1.+`) should pick up a newly released version. - A previous download was corrupted/partial and you want a clean re-verify. - A CI "nightly against latest" job that must always resolve fresh. ## Programmatic / config alternatives Instead of the flag you can tighten the cache TTL in the build: ```kotlin configurations.all { resolutionStrategy { cacheChangingModulesFor(0, "seconds") // always recheck SNAPSHOTs cacheDynamicVersionsFor(10, "minutes") // dynamic version listings } } ``` ## What it is NOT It is not the same as `--offline` (which forbids the network) nor deleting `caches/modules-2` (which forces a full re-download of everything). `--refresh-dependencies` is the targeted middle ground: trust the network as the source of truth for this build, but reuse byte-identical artifacts.

  • Does --refresh-dependencies re-download every artifact byte-for-byte?
    No. It re-fetches metadata and re-verifies checksums, but if a cached artifact's checksum still matches the remote, the cached bytes are reused — only changed/missing artifacts are actually re-downloaded.
  • How could you achieve the same effect without passing the flag every time?
    Tighten the resolution strategy: cacheChangingModulesFor(0, "seconds") for SNAPSHOTs and cacheDynamicVersionsFor(...) for dynamic versions. That bakes the freshness policy into the build instead of relying on a CLI flag.
  • Why is it usually a no-op for a fixed release version like 1.4.2?
    Fixed releases are treated as immutable — Gradle assumes the coordinates map to unchanging content, so there's nothing to refresh. The flag mainly affects changing modules and dynamic versions.

saying these in an interview costs you the question

  • Saying it deletes or clears the cache — it refreshes metadata but reuses byte-identical artifacts.
  • Claiming it changes fixed-release resolution — it effectively doesn't.
  • Confusing it with --offline (the opposite intent).

context

resolving links…