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
├── wrapper
│   └── dists // (6)
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties // (7)

  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. Distributions downloaded by the Gradle Wrapper

  7. 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)
├── build.gradle or build.gradle.kts // (5)
├── gradle.properties // (6)
├── gradlew // (7)
├── gradlew.bat // (7)
└── settings.gradle or settings.gradle.kts // (8)

  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. The project’s Gradle build script

  6. Project-specific Gradle configuration properties

  7. Scripts for executing builds using the Gradle Wrapper

  8. The project’s settings file

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.