Introduction

The fastest way to force Gradle to redownload dependencies is the --refresh-dependencies flag. Append it to any Gradle command to bypass the local cache and fetch fresh copies of all resolved artifacts from remote repositories.

gradle build --refresh-dependencies

This handles the majority of cases: corrupted downloads, stale SNAPSHOT versions, and dependency resolution that stopped picking up new releases. For more severe cache corruption, you may need to delete the cache directory entirely.

How Gradle Caching Works

Gradle stores downloaded dependencies in a local cache at ~/.gradle/caches/ (Linux/macOS) or C:\Users\<username>\.gradle\caches\ (Windows). The cache has two main sections:

• Module cache (modules-2/): Stores downloaded JARs, POMs, and metadata indexed by group, artifact, and version.
• File locks and hashes: Gradle tracks checksums to verify artifact integrity.

When you run a build, Gradle checks the local cache first. If the artifact exists and the checksum matches, it skips the network request entirely. This is why builds are fast after the first run but also why stale or corrupted artifacts can persist.

For SNAPSHOT dependencies, Gradle caches them for 24 hours by default. During that window, it will not check the remote repository for updates unless forced.

Method 1: --refresh-dependencies

This flag tells Gradle to revalidate all cached dependencies against the remote repositories:

1# With Gradle wrapper (recommended)
2./gradlew build --refresh-dependencies
3
4# With system Gradle
5gradle build --refresh-dependencies

What this actually does:

1. Checks the remote repository for each dependency.
2. Downloads the artifact if the remote version is newer or the local copy's checksum does not match.
3. Updates the local cache with fresh metadata.

This does not delete the cache. It revalidates it. For most "stale dependency" issues, this is the correct fix.

Method 2: Delete the Gradle Cache

When --refresh-dependencies does not solve the problem, the cache itself may be corrupted. Delete it and let Gradle rebuild from scratch.

1# Stop all Gradle daemons first
2./gradlew --stop
3
4# Delete the dependency cache
5rm -rf ~/.gradle/caches/
6
7# Rebuild (downloads everything fresh)
8./gradlew build

On Windows:

1# Stop daemons
2.\gradlew.bat --stop
3
4# Delete cache
5Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\caches"
6
7# Rebuild
8.\gradlew.bat build

This affects all Gradle projects on the machine, not just the current one. Every project's next build will re-download all dependencies.

Method 3: Delete a Specific Dependency

If you know exactly which dependency is corrupted, you can delete only that artifact from the cache instead of wiping everything:

1# Delete a specific artifact (e.g., com.google.guava:guava)
2find ~/.gradle/caches -path "*/com.google.guava/guava*" -exec rm -rf {} +
3
4# Rebuild
5./gradlew build

This is more surgical than deleting the entire cache and avoids the long rebuild time for projects with hundreds of dependencies.

Method 4: Force Resolution Strategy in build.gradle

For programmatic control, you can configure Gradle's resolution strategy to force specific dependencies to refresh on every build:

1// build.gradle
2configurations.all {
3    resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
4    resolutionStrategy.cacheDynamicVersionsFor 0, 'seconds'
5}

In Kotlin DSL:

1// build.gradle.kts
2configurations.all {
3    resolutionStrategy {
4        cacheChangingModulesFor(0, "seconds")
5        cacheDynamicVersionsFor(0, "seconds")
6    }
7}

• cacheChangingModulesFor controls how long SNAPSHOT dependencies are cached.
• cacheDynamicVersionsFor controls how long dynamic versions (like 1.+ or latest.release) are cached.

Setting both to 0 seconds forces Gradle to check the remote repository on every build. This is useful during active development but slows down builds, so do not leave it in production build scripts permanently.

Method 5: Invalidate Caches in IntelliJ IDEA

If you are using IntelliJ IDEA and Gradle sync is stuck on old dependencies, the IDE has its own cache layer on top of Gradle's:

1. Go to File > Invalidate Caches.
2. Check Clear file system cache and Local History.
3. Click Invalidate and Restart.
4. After restart, reimport the Gradle project.

This resolves cases where Gradle itself sees the correct dependencies but IntelliJ's index still references old versions.

Method Comparison

Configuring SNAPSHOT Cache Duration

For projects that depend on SNAPSHOT versions from a CI artifact repository, the default 24-hour cache can cause confusion. Configure a shorter window:

configurations.all {
    resolutionStrategy.cacheChangingModulesFor 10, 'minutes'
}

You can also mark specific dependencies as "changing" explicitly:

1dependencies {
2    implementation('com.example:my-lib:1.0-SNAPSHOT') {
3        changing = true
4    }
5}

Gradle only applies cacheChangingModulesFor to dependencies marked as changing. SNAPSHOT versions are marked automatically, but custom versioning schemes (like 1.0-beta-latest) need the explicit changing = true.

Verifying Dependencies After Refresh

After forcing a redownload, verify that the correct version resolved:

1# Show the full dependency tree
2./gradlew dependencies --configuration runtimeClasspath
3
4# Check a specific dependency
5./gradlew dependencyInsight --dependency guava --configuration runtimeClasspath

The dependencyInsight task shows which version was selected, why, and whether any version conflicts were resolved by Gradle's conflict resolution.

Common Pitfalls

Running --refresh-dependencies on every build defeats the purpose of caching and significantly slows down build times. Use it as a troubleshooting step, not a permanent flag.

Deleting ~/.gradle/caches/ while Gradle daemons are still running can cause file lock errors and leave the cache in an inconsistent state. Always run ./gradlew --stop first.

Confusing Gradle's dependency cache with the build cache (~/.gradle/caches/build-cache-1/) leads to deleting the wrong directory. The build cache stores task outputs for incremental builds. The dependency cache stores downloaded JARs. Deleting both works but is more disruptive than necessary.

Using dynamic version ranges like 1.+ in production builds makes dependency resolution unpredictable regardless of cache state. Pin versions explicitly and use --refresh-dependencies only for troubleshooting.

Forgetting that Gradle wrapper (./gradlew) and system Gradle may use different Gradle versions with different cache formats can cause confusion when troubleshooting. Always prefer the wrapper for consistency.

Summary

• Use ./gradlew build --refresh-dependencies as the first troubleshooting step for stale dependencies.
• Delete ~/.gradle/caches/ only when cache corruption is persistent, and always stop daemons first.
• Use cacheChangingModulesFor(0, "seconds") in build.gradle to force fresh SNAPSHOT resolution during active development.
• Verify resolved versions with ./gradlew dependencies or dependencyInsight.
• Never leave aggressive cache-busting settings in production build scripts.
• In IntelliJ IDEA, invalidate IDE caches separately if Gradle sync does not reflect updated dependencies.