Gradle-managed Directories and Caches
Gradle uses two main directories to perform and manage its work and stores several caches under them:
1. Gradle User Home directory
By default, the Gradle User Home (~/.gradle or C:\Users\<USERNAME>\.gradle) stores global configuration properties, initialization scripts, caches, and log files.
It can be set with the environment variable GRADLE_USER_HOME.
Not to be confused with the GRADLE_HOME, the optional installation directory for Gradle.
|
It is roughly structured as follows:
├── caches (1)
├── daemon (2)
├── init.d (3)
├── jdks (4)
├── wrapper
│ └── dists (5)
└── gradle.properties (6)| 1 | Caches. |
| 2 | Registry and logs of the Gradle Daemon. |
| 3 | Global initialization scripts. |
| 4 | JDKs downloaded by the toolchain support. |
| 5 | Distributions downloaded by the Gradle Wrapper. |
| 6 | Global Gradle configuration properties. |
2. Project Root directory
The project root directory contains all source files from your project.
It also contains files and directories Gradle generates, such as .gradle and build.
While the former are usually checked into source control, the latter are transient files Gradle uses to support features like incremental builds.
The anatomy of a typical project root directory looks as follows:
├── .gradle (1)
├── build (2)
├── gradle
│ └── wrapper (3)
├── gradle.properties (4)
├── gradlew (5)
├── gradlew.bat (5)
├── settings.gradle.kts (6)
├── subproject-one (7)
| └── build.gradle.kts (8)
├── subproject-two (7)
| └── build.gradle.kts (8)
└── ⋮| 1 | Project-specific cache directory generated by Gradle. |
| 2 | The build directory of this project into which Gradle generates all build artifacts. |
| 3 | Contains the JAR file and configuration of the Gradle Wrapper. |
| 4 | Project-specific Gradle configuration properties. |
| 5 | Scripts for executing builds using the Gradle Wrapper. |
| 6 | The project’s settings file where the list of subprojects is defined. |
| 7 | Usually, a project is organized into one or multiple subprojects. |
| 8 | Each subproject has its own Gradle build script. |
3. Caches
Gradle uses several on-disk caches to make repeat builds faster. These caches live under the directories described in Gradle User Home and Project Root. In most cases they do not require manual management. Gradle creates, uses, and cleans them automatically.
Version-specific caches
These caches live under caches/<gradle-version>/ in the Gradle User Home and are tied to a specific Gradle release.
They are recreated on first use of that Gradle version.
| Directory | Contents |
|---|---|
|
JARs that Gradle generates on first use of the Gradle version. |
|
Compiled Kotlin DSL scripts and accessors. |
|
Compiled Groovy DSL scripts. |
Shared caches
These caches live directly under caches/ in the Gradle User Home and are shared across Gradle versions.
The trailing number in each directory name is the on-disk format version; see Format versions in cache directory names.
| Directory | Contents |
|---|---|
|
Local Build Cache entries: task outputs keyed by input hashes. |
|
Instrumented JARs produced by Gradle’s classpath instrumentation. |
|
Downloaded module dependencies (POMs, JARs, metadata). See Dependency caching. |
|
Outputs of artifact transforms. |
Project-local caches
These caches live under .gradle/ in the project root and are specific to a single project.
| Directory | Contents |
|---|---|
|
Version-specific build state for incremental build (snapshots of task inputs and outputs from the previous build). |
|
Configuration Cache state for this project: the serialized task graph, configuration inputs, and metadata used to skip the configuration phase on subsequent builds. |
Format versions in cache directory names
Several caches use a trailing format version in their directory name (for example, modules-2, jars-9, transforms-3, build-cache-1).
The number changes when Gradle changes the on-disk layout for that cache.
When multiple format versions of the same cache exist on disk (for example, both transforms-3 and transforms-4), the older one is left behind from a previous Gradle version and is cleaned up after the inactivity threshold.
Only the current format is being written by the current Gradle version.
Cleanup of caches and distributions
Gradle automatically cleans its caches in both the Gradle User Home and the project directory.
By default, the cleanup runs in the background when the Gradle daemon is stopped or shut down.
If using --no-daemon, it runs in the foreground after the build session.
Gradle User Home cleanup
The following cleanup strategies are applied periodically (by default, once every 24 hours):
-
Version-specific caches in all
caches/<GRADLE_VERSION>/directories are checked for whether they are still in use.If not, directories for release versions are deleted after 30 days of inactivity, and snapshot versions after 7 days.
-
Shared caches in
caches/(e.g.,jars-*) are checked for whether they are still in use.If no Gradle version still uses them, they are deleted.
-
Files in shared caches used by the current Gradle version in
caches/(e.g.,jars-9ormodules-2) are checked for when they were last accessed.Depending on whether the file can be recreated locally or downloaded from a remote repository, it will be deleted after 7 or 30 days, 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.
-
Daemon log files in
daemon/<GRADLE_VERSION>/directories are checked for their last modification time.Log files older than 14 days are automatically deleted to prevent the daemon directory from growing indefinitely.
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/9.7.0-20260605013821+0000/ are checked periodically (at most, every 24 hours) to determine whether they are still in use.
They are deleted if they haven’t been used for 7 days.
Configuring cleanup of caches and distributions
The retention periods of the various caches can be configured.
Caches are classified into six categories:
-
Released wrapper distributions: Distributions and related version-specific caches corresponding to released versions (e.g.,
4.6.2or8.0).Default retention for unused versions is 30 days.
-
Snapshot wrapper distributions: Distributions and related version-specific caches corresponding to snapshot versions (e.g.
7.6-20221130141522+0000).Default retention for unused versions is 7 days.
-
Downloaded resources: Shared caches downloaded from a remote repository (e.g., cached dependencies).
Default retention for unused resources is 30 days.
-
Created resources: Shared caches that Gradle creates during a build (e.g., artifact transforms).
Default retention for unused resources is 7 days.
-
Build cache: The local build cache (e.g., build-cache-1).
Default retention for unused build cache entries is 7 days.
-
Daemon logs: Log files from Gradle Daemon processes in
daemon/<GRADLE_VERSION>/directories.Default retention for daemon logs is 14 days.
The retention period for each category can be configured independently via an init script in the Gradle User Home:
beforeSettings {
caches {
releasedWrappers.setRemoveUnusedEntriesAfterDays(45)
snapshotWrappers.setRemoveUnusedEntriesAfterDays(10)
downloadedResources.setRemoveUnusedEntriesAfterDays(45)
createdResources.setRemoveUnusedEntriesAfterDays(10)
buildCache.setRemoveUnusedEntriesAfterDays(5)
daemonLogs.setRemoveUnusedEntriesAfterDays(14)
}
}beforeSettings { settings ->
settings.caches {
releasedWrappers.removeUnusedEntriesAfterDays = 45
snapshotWrappers.removeUnusedEntriesAfterDays = 10
downloadedResources.removeUnusedEntriesAfterDays = 45
createdResources.removeUnusedEntriesAfterDays = 10
buildCache.removeUnusedEntriesAfterDays = 5
daemonLogs.removeUnusedEntriesAfterDays = 14
}
}The frequency at which cache cleanup is invoked is also configurable.
There are three possible settings:
-
DEFAULT: Cleanup is performed periodically in the background (currently once every 24 hours).
-
DISABLED: Never cleanup Gradle User Home.
This is useful in cases where Gradle User Home is ephemeral or delaying cleanup is desirable until an explicit point.
-
ALWAYS: Cleanup is performed at the end of each build session.
This is useful in cases where it’s desirable to ensure that cleanup has occurred before proceeding.
However, this performs cache cleanup during the build (rather than in the background), which can be expensive, so this option should only be used when necessary.
To disable cache cleanup:
beforeSettings {
caches {
cleanup = Cleanup.DISABLED
}
}beforeSettings { settings ->
settings.caches {
cleanup = Cleanup.DISABLED
}
}
Cache cleanup settings can only be configured via init scripts and should be placed under the init.d directory in Gradle User Home.
This effectively couples the configuration of cache cleanup to the Gradle User Home those settings apply to and limits the possibility of different conflicting settings from different projects being applied to the same directory.
|
Multiple versions of Gradle sharing a Gradle User Home
It is common to share a single Gradle User Home between multiple versions of Gradle.
As stated above, caches in Gradle User Home are version-specific. Different versions of Gradle will perform maintenance on only the version-specific caches associated with each version.
On the other hand, some caches are shared between versions (e.g., the dependency artifact cache or the artifact transform cache).
Beginning with Gradle version 8.0, the cache cleanup settings can be configured to custom retention periods. However, older versions have fixed retention periods (7 or 30 days, depending on the cache). These shared caches could be accessed by versions of Gradle with different settings to retain cache artifacts.
This means that:
-
If the retention period is not customized, all versions that perform cleanup will have the same retention periods. There will be no effect due to sharing a Gradle User Home with multiple versions.
-
If the retention period is customized for Gradle versions greater than or equal to version 8.0 to use retention periods shorter than the previously fixed periods, there will also be no effect.
The versions of Gradle aware of these settings will cleanup artifacts earlier than the previously fixed retention periods, and older versions will effectively not participate in the cleanup of shared caches.
-
If the retention period is customized for Gradle versions greater than or equal to version 8.0 to use retention periods longer than the previously fixed periods, the older versions of Gradle may clean the shared caches earlier than what is configured.
In this case, if it is desirable to maintain these shared cache entries for newer versions for longer retention periods, they will not be able to share a Gradle User Home with older versions. They will need to use a separate directory.
Another consideration when sharing the Gradle User Home with versions of Gradle before version 8.0 is that the DSL elements to configure the cache retention settings are unavailable in earlier versions, so this must be accounted for in any init script shared between versions. This can easily be handled by conditionally applying a version-compliant script.
The version-compliant script should reside somewhere other than the init.d directory (such as a sub-directory), so it is not automatically applied.
|
To configure cache cleanup in a version-safe manner:
if (GradleVersion.current() >= GradleVersion.version("8.0")) {
apply(from = "gradle8/cache-settings.init.gradle.kts")
}if (GradleVersion.current() >= GradleVersion.version('8.0')) {
apply from: "gradle8/cache-settings.init.gradle"
}Version-compliant cache configuration script:
beforeSettings {
caches {
releasedWrappers { setRemoveUnusedEntriesAfterDays(45) }
snapshotWrappers { setRemoveUnusedEntriesAfterDays(10) }
downloadedResources { setRemoveUnusedEntriesAfterDays(45) }
createdResources { setRemoveUnusedEntriesAfterDays(10) }
buildCache { setRemoveUnusedEntriesAfterDays(5) }
}
}beforeSettings { settings ->
settings.caches {
releasedWrappers.removeUnusedEntriesAfterDays = 45
snapshotWrappers.removeUnusedEntriesAfterDays = 10
downloadedResources.removeUnusedEntriesAfterDays = 45
createdResources.removeUnusedEntriesAfterDays = 10
buildCache.removeUnusedEntriesAfterDays = 5
}
}Cache marking
Beginning with Gradle version 8.1, Gradle supports marking caches with a CACHEDIR.TAG file.
It follows the format described in the Cache Directory Tagging Specification. The purpose of this file is to allow tools to identify the directories that do not need to be searched or backed up.
By default, the directories caches, wrapper/dists, daemon, and jdks in the Gradle User Home are marked with this file.
Configuring cache marking
The cache marking feature can be configured via an init script in the Gradle User Home:
beforeSettings {
caches {
// Disable cache marking for all caches
markingStrategy = MarkingStrategy.NONE
}
}beforeSettings { settings ->
settings.caches {
// Disable cache marking for all caches
markingStrategy = MarkingStrategy.NONE
}
}
Cache marking settings can only be configured via init scripts and should be placed under the init.d directory in Gradle User Home. This effectively couples the configuration of cache marking to the Gradle User Home to which those settings apply and limits the possibility of different conflicting settings from different projects being applied to the same directory.
|