How to Clean Gradle Cache Safely

What is in ~/.gradle

The Gradle user home is ~/.gradle by default. The GRADLE_USER_HOME environment variable moves it elsewhere. This command only reads and shows what takes the space:

du -h -d 1 ~/.gradle | sort -h

Gradle already cleans up automatically

Before you delete anything, know that Gradle removes unused entries from its caches on its own. By default it removes:

• downloaded resources not used for 30 days;
• resources Gradle created itself not used for 7 days;
• released wrapper distributions not used for 30 days (snapshots after 7 days);
• version-specific cache folders for Gradle versions not used for 30 days.

Cleanup runs at most once every 24 hours, in the background when a Gradle daemon stops. So a cache that stays large usually means it is in active use, or that you rarely run Gradle and the cleanup has not run yet.

With Gradle 8.0 and later you can change the retention with an init script. Gradle's documentation uses a file such as ~/.gradle/init.d/cache-settings.init.gradle.kts:

beforeSettings {
    caches {
        downloadedResources.setRemoveUnusedEntriesAfterDays(15)
        createdResources.setRemoveUnusedEntriesAfterDays(5)
        releasedWrappers.setRemoveUnusedEntriesAfterDays(15)
    }
}

The old org.gradle.cache.cleanup property in gradle.properties is deprecated in Gradle 8 and has no effect in Gradle 9. Use the init script instead.

Clean a project's build output

Each project also has its own build folders, one per module. They are separate from the shared cache and often larger than you expect.

./gradlew clean

The clean task deletes the project's build directory and everything in it. It does not touch ~/.gradle. The next build recompiles everything, so it takes longer.

Projects you no longer work on can keep gigabytes of build output. Running ./gradlew clean in each old project, or deleting its build folders, frees that space without touching the source.

See which Gradle versions you still use

Each Gradle version your projects ever used left a distribution in ~/.gradle/wrapper/dists. List them, and compare with the versions your current projects ask for. Both commands only read:

ls ~/.gradle/wrapper/dists
grep -r --include=gradle-wrapper.properties distributionUrl ~/Projects

Replace ~/Projects with the folder that holds your code. Versions that no project mentions any more can go; Gradle's automatic cleanup also removes them once they have not been used for 30 days.

Delete the Gradle caches by hand

If you need the space right away, you can remove parts of ~/.gradle yourself. Gradle's documentation says the caches normally need no manual management and does not describe deleting them, so treat this as a last resort and expect a slow next build.

Stop all Gradle daemons first, and close Android Studio or IntelliJ IDEA. Deleting files while a daemon uses them can leave builds in a broken state. The next build downloads every dependency again, which needs a network connection and can take a long time.

1. Stop the daemons with ./gradlew --stop inside a project, or gradle --stop. This stops daemons of that Gradle version; daemons of other versions stop by themselves after three hours idle, or appear in jps.
2. Move the folder you want to clear to the Trash, for example ~/.gradle/caches or old versions in ~/.gradle/wrapper/dists, instead of deleting it right away.
3. Run a build of a project you use, check that it works, then empty the Trash.

Wrapper distributions of Gradle versions none of your projects use any more are a good, low-risk target: check distributionUrl in each project's gradle/wrapper/gradle-wrapper.properties to see which versions you still need.

Keep ~/.gradle/gradle.properties and any init scripts in ~/.gradle/init.d. They are your configuration, not cache.

IDE caches are separate

Android Studio and IntelliJ IDEA keep their own caches and indexes, separate from Gradle's. If the IDE is slow or shows stale errors, use File > Invalidate Caches in the IDE instead of deleting folders: it clears the IDE's caches and restarts it, and leaves Gradle's caches alone.

After an upgrade, folders of old IDE versions can remain in your Library. The IDE's own settings and documentation describe where they are and how to remove them; check them before deleting, because they also hold settings you may want to import.

Android Studio: emulator storage

For Android developers, emulator images often take more space than Gradle. Each virtual device stores its data in ~/.android/avd/<name>.avd/.

• In Android Studio's Device Manager, open a device's menu and choose Wipe Data to reset it, or Delete to remove the virtual device completely.
• Show on Disk in the same menu opens the device's folder, so you can see its size first.
• From the command line, avdmanager list avd lists virtual devices and avdmanager delete avd -n <name> deletes one.

Wiping or deleting a virtual device removes the apps, settings and files inside it.

Questions and answers

Does ./gradlew clean free space in ~/.gradle?

No. clean only deletes the project's own build directory. The shared caches in ~/.gradle are managed by Gradle's automatic cleanup.

What about the .gradle folder inside a project?

Each project also has a .gradle folder at its root with project-specific caches. Gradle's documentation says the configuration cache, stored in .gradle/configuration-cache, can be cleared by simply deleting that directory. Delete it with the IDE closed and no build running; Gradle recreates it on the next build.

Why is the cache still large after cleanup?

Automatic cleanup only removes entries that have not been used for the retention period. Dependencies of projects you build regularly are in use and stay, which is intended: they keep your builds fast.

Can I move the Gradle cache to another drive?

Yes: set GRADLE_USER_HOME to a folder on that drive. Builds then depend on the drive being connected, and a slow drive makes builds slower.

Will deleting caches change my build results?

No. Gradle downloads the same dependency versions again, as declared in your build files. Only the first build takes longer.

Do I need to stop Gradle daemons for ./gradlew clean?

No. clean is a normal build task and runs through the daemon like any other. Stopping daemons matters only when you delete files in ~/.gradle by hand.