The fastest way to clear the Gradle cache is to delete the ~/.gradle/caches/ directory. For the project-level build cache, run ./gradlew clean. To also stop the Gradle daemon (which holds file locks on cached artifacts), run ./gradlew --stop before deleting anything. Understanding which cache directory to clear, and why, saves you from unnecessary full-cache wipes that add minutes to your next build.

Gradle's Cache Structure

Gradle maintains several cache directories, each serving a different purpose. Clearing the wrong one either does nothing or forces a much longer rebuild than necessary.

1~/.gradle/
2  caches/
3    modules-2/          # Downloaded dependency JARs and POMs
4    transforms-3/       # Artifact transforms (e.g., desugaring, resource merging)
5    build-cache-1/      # Task output cache (shared across projects)
6    jars-9/             # Cached classpath analysis
7    journal-1/          # File system access journal
8  wrapper/
9    dists/              # Downloaded Gradle distributions (not usually worth clearing)
10  daemon/
11    <version>/          # Daemon logs and registry
12
13<project>/
14  .gradle/              # Project-specific caches (task history, file hashes)
15  build/                # Build outputs (classes, JARs, reports)

Option 1: Delete the Global Cache Directory

This is the most thorough approach. It removes all downloaded dependencies, cached transforms, and build cache entries.

1# Stop the daemon first to release file locks
2./gradlew --stop
3
4# Delete the global cache
5rm -rf ~/.gradle/caches/
6
7# On Windows (PowerShell)
8./gradlew --stop
9Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\caches"

After this, the next build will re-download every dependency and re-execute every task. On a project with hundreds of dependencies, this can add several minutes.

Option 2: Clear Only the Dependency Cache

If your issue is a corrupted or stale dependency, target just the module cache.

1# Remove only downloaded dependencies
2rm -rf ~/.gradle/caches/modules-2/
3
4# Or remove a specific group's artifacts
5rm -rf ~/.gradle/caches/modules-2/files-2.1/com.google.guava/
6
7# On Windows
8Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\caches\modules-2\files-2.1\com.google.guava"

This is the right choice when you see errors like "Could not resolve artifact" or when a dependency appears to be the wrong version despite your build file being correct.

Option 3: Clean the Project Build Directory

For project-level issues (stale compiled classes, outdated generated code), the clean task is sufficient.

1# Deletes the build/ directory
2./gradlew clean
3
4# Clean and rebuild
5./gradlew clean build
6
7# Clean a specific subproject in a multi-module build
8./gradlew :app:clean
9./gradlew :library:clean

This does not touch the global cache. Dependencies remain cached, and only the compiled output is regenerated.

Option 4: Invalidate the Build Cache

Gradle's build cache stores task outputs keyed by inputs. If you suspect the cache is returning incorrect results (rare, but possible after Gradle upgrades or plugin changes):

1# Delete the local build cache
2rm -rf ~/.gradle/caches/build-cache-1/
3
4# Or disable the build cache for a single run
5./gradlew build --no-build-cache
6
7# Or use the deprecated (pre-Gradle 8) command
8./gradlew cleanBuildCache

Note: cleanBuildCache was deprecated in Gradle 7 and removed in Gradle 8. Direct deletion of build-cache-1/ is now the recommended approach.

Option 5: Stop the Gradle Daemon

The Gradle daemon is a long-running process that caches project information in memory. If you are experiencing phantom build issues that persist after clearing disk caches, the daemon's in-memory state may be stale.

1# Stop all running daemons
2./gradlew --stop
3
4# Verify no daemons are running
5./gradlew --status
6
7# Force a build without the daemon (useful for debugging)
8./gradlew build --no-daemon

Stopping the daemon is also necessary before deleting cache directories on Windows, because the daemon holds file locks that prevent deletion.

Option 6: Refresh Dependencies Without Clearing Cache

If the issue is a SNAPSHOT dependency that has been updated upstream, you can force Gradle to re-check remote repositories without deleting the cache.

1# Force refresh of all dependencies
2./gradlew build --refresh-dependencies
3
4# This re-downloads changed artifacts but keeps unchanged ones cached

This is faster than a full cache clear because it only downloads dependencies whose checksums have changed since the last check.

Gradle Cache Configuration

You can control cache behavior in gradle.properties or settings.gradle:

1# gradle.properties
2
3# Disable the build cache entirely
4org.gradle.caching=false
5
6# Set a custom cache directory
7org.gradle.caching.directory=/path/to/custom/cache
8
9# Control dependency caching TTL for dynamic versions
10# (e.g., how long to cache SNAPSHOT lookups)
11# In build.gradle:

1// build.gradle - configure cache expiration for changing dependencies
2configurations.all {
3    resolutionStrategy {
4        // Re-check SNAPSHOT dependencies every build
5        cacheChangingModulesFor 0, 'seconds'
6
7        // Re-check dynamic versions (e.g., 1.0.+) every 24 hours
8        cacheDynamicVersionsFor 24, 'hours'
9    }
10}

Decision Flowchart

Choose the right cache-clearing strategy based on your symptom:

1Build fails with "Could not resolve dependency"
2  -> rm -rf ~/.gradle/caches/modules-2/
3  -> ./gradlew build --refresh-dependencies
4
5Build uses wrong version of a SNAPSHOT
6  -> ./gradlew build --refresh-dependencies
7
8Stale compiled classes or generated code
9  -> ./gradlew clean build
10
11Build cache returns wrong task outputs
12  -> rm -rf ~/.gradle/caches/build-cache-1/
13  -> ./gradlew build --no-build-cache
14
15Everything is broken, nothing makes sense
16  -> ./gradlew --stop
17  -> rm -rf ~/.gradle/caches/
18  -> rm -rf <project>/.gradle/
19  -> ./gradlew clean build

Common Pitfalls

• Clearing the entire ~/.gradle/ directory instead of just caches/. The wrapper/dists/ directory contains downloaded Gradle distributions. Deleting it forces a re-download of the Gradle wrapper, which is slow and unnecessary. The gradle.properties file in ~/.gradle/ contains your global configuration. Never delete the entire ~/.gradle/ directory blindly.
• Forgetting to stop the daemon on Windows. The Gradle daemon locks files in the cache directory. Deleting files while the daemon is running produces partial deletions and "Access denied" errors. Always run ./gradlew --stop first.
• Using cleanBuildCache on Gradle 8+. This task was removed. Use direct directory deletion or --no-build-cache instead.
• Running --refresh-dependencies on every build. This flag forces Gradle to contact remote repositories for every dependency on every build, which significantly slows down builds. Use it as a one-time fix, not a permanent workaround.
• Not understanding incremental builds. Gradle tracks input/output hashes for each task. Clearing caches invalidates this tracking, forcing full recompilation. If your issue is limited to a single module, use ./gradlew :module:clean instead of a global cache wipe.
• Clearing caches in CI/CD without a cache restore step. Many CI systems (GitHub Actions, GitLab CI) cache ~/.gradle/caches/ between runs. If you clear it without updating the CI cache configuration, every subsequent pipeline run starts with a cold cache.

Summary

Gradle maintains global caches (dependencies in ~/.gradle/caches/modules-2/, build outputs in build-cache-1/) and project-level caches (.gradle/ and build/ directories). Match the cache-clearing approach to the problem: use --refresh-dependencies for stale SNAPSHOT versions, ./gradlew clean for stale build outputs, targeted deletion in modules-2/ for corrupted dependencies, and a full rm -rf ~/.gradle/caches/ only as a last resort. Always stop the Gradle daemon before deleting cache files. On CI systems, be mindful of pipeline cache configurations when clearing local caches.