Gradle uses two main directories to perform and manage its work: the Gradle user home directory and the Project root directory. The following two sections describe what is stored in each of them and how transient files and directories are cleaned up.

Gradle user home directory

The Gradle user home directory ($USER_HOME/.gradle by default) is used to store global configuration properties and initialization scripts as well as caches and log files. It is roughly structured as follows:

├── caches (1)
│   ├── 4.8 (2)
│   ├── 4.9 (2)
│   ├── ⋮
│   ├── jars-3 (3)
│   └── modules-2 (3)
├── daemon (4)
│   ├── ⋮
│   ├── 4.8
│   └── 4.9
├── init.d (5)
│   └── my-setup.gradle
├── jdks (6)
│   ├── ⋮
│   └── jdk-14.0.2+12
├── wrapper
│   └── dists (7)
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties (8)
1 Global cache directory (for everything that’s not project-specific)
2 Version-specific caches (e.g. to support incremental builds)
3 Shared caches (e.g. for artifacts of dependencies)
4 Registry and logs of the Gradle Daemon
5 Global initialization scripts
6 JDKs downloaded by the toolchain support
7 Distributions downloaded by the Gradle Wrapper
8 Global Gradle configuration properties

Cleanup of caches and distributions

From version 4.10 onwards, Gradle automatically cleans its user home directory. The cleanup runs in the background when the Gradle daemon is stopped or shuts down. If using --no-daemon, it runs in the foreground after the build session with a visual progress indicator.

The following cleanup strategies are applied periodically (at most every 24 hours):

  • Version-specific caches in caches/<gradle-version>/ are checked for whether they are still in use.If not, directories for release versions are deleted after 30 days of inactivity, snapshot versions after 7 days of inactivity.

  • Shared caches in caches/ (e.g. jars-*) are checked for whether they are still in use.If there’s no Gradle version that still uses them, they are deleted.

  • Files in shared caches used by the current Gradle version in caches/ (e.g. jars-3 or modules-2) are checked for when they were last accessed.Depending on whether the file can be recreated locally or would have to be downloaded from a remote repository again, it will be deleted after 7 or 30 days of not being accessed, respectively.

  • Gradle distributions in wrapper/dists/ are checked for whether they are still in use, i.e. whether there’s a corresponding version-specific cache directory.Unused distributions are deleted.

Project root directory

The project root directory contains all source files that are part of your project. In addition, it contains files and directories that are generated by Gradle such as .gradle and build. While the former are usually checked in to source control, the latter are transient files used by Gradle to support features like incremental builds. Overall, the anatomy of a typical project root directory looks roughly as follows:

├── .gradle (1)
│   ├── 4.8 (2)
│   ├── 4.9 (2)
│   └── ⋮
├── build (3)
├── gradle
│   └── wrapper (4)
├── gradle.properties (5)
├── gradlew (6)
├── gradlew.bat (6)
├── settings.gradle or settings.gradle.kts (7)
├── subproject-one (8)
|   └── build.gradle or build.gradle.kts (9)
├── subproject-two (8)
|   └── build.gradle or build.gradle.kts (9)
└── ⋮
1 Project-specific cache directory generated by Gradle
2 Version-specific caches (e.g. to support incremental builds)
3 The build directory of this project into which Gradle generates all build artifacts.
4 Contains the JAR file and configuration of the Gradle Wrapper
5 Project-specific Gradle configuration properties
6 Scripts for executing builds using the Gradle Wrapper
7 The project’s settings file where the list of subprojects is defined
8 Usually a project is organized into one or multiple subprojects
9 Each subproject has its own Gradle build script

Project cache cleanup

From version 4.10 onwards, Gradle automatically cleans the project-specific cache directory. After building the project, version-specific cache directories in .gradle/<gradle-version>/ are checked periodically (at most every 24 hours) for whether they are still in use. They are deleted if they haven’t been used for 7 days.