Android - Managing Gradle Caches

Over time, local caches used by build tools and IDEs can become corrupted or hold onto outdated artifacts, leading to perplexing build failures or unexpected behavior. Performing a "deep clean" by clearing these caches forces your system to download fresh dependencies and rebuild its understanding of your project structure.

This guide covers the most thorough process for ensuring a clean build environment:

1. Stopping the Gradle Daemon
2. Clearing the global .gradle cache directory
3. Clearing the local Maven repository (.m2)
4. Invalidating caches within your IDE (Android Studio / IntelliJ IDEA)

Before You Begin

• Close Your IDE: It's crucial to close Android Studio, IntelliJ IDEA, VS Code, or any other development environment. These applications can hold file locks on the directories you need to delete.
• Backup Custom Global Settings: If you have custom configurations in a global ~/.gradle/gradle.properties file (like repository credentials or JVM settings), make sure to back it up before proceeding.

1. Stop Gradle Daemons

First, ensure no Gradle processes are running in the background, as they can interfere with deleting the cache directory.

Open your terminal or command prompt and run the following command:

./gradlew --stop

If you are not in a project directory, you can use:

gradle --stop

2. Clear the .gradle Directory

The .gradle directory in your user's home folder is the primary cache for Gradle. It stores downloaded dependencies, build caches, wrapper distributions, and daemon logs. Deleting it is the most critical step.

macOS

Open the Terminal application.

Run the following command to recursively and forcefully remove the directory:

# This command will permanently delete the .gradle folder in your home directory
rm -rf ~/.gradle

Linux

Open your preferred terminal emulator.

Execute the following command to delete the .gradle directory:

# This command will permanently delete the .gradle folder in your home directory
rm -rf ~/.gradle

Windows

Open File Explorer.

In the address bar, type %USERPROFILE% and press Enter. This will take you to your user directory (e.g., C:\Users\YourUsername).

Locate the .gradle folder and delete it. You can do this by right-clicking and selecting Delete, or by selecting the folder and pressing the Delete key.

Alternatively, you can use PowerShell for a faster command-line approach:

# This command will permanently delete the .gradle folder
Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle"

3. Clear the Maven Local Repository (.m2)

Even if your project primarily uses Gradle, it might still resolve some dependencies that were published to a Maven repository. Other tools on your system may also use this cache. Clearing it helps ensure you aren't using a corrupted artifact from this location.

The process is very similar to clearing the .gradle directory.

macOS

Open the Terminal application.

Run the following command. Note that we are deleting the repository subfolder, not the entire .m2 directory, to preserve any custom settings.xml file you might have.

# This command will permanently delete your local Maven artifact cache
rm -rf ~/.m2/repository

Linux

Open your terminal.

Execute the command below:

# This command will permanently delete your local Maven artifact cache
rm -rf ~/.m2/repository

Windows

Open File Explorer.

In the address bar, type %USERPROFILE%\.m2 and press Enter.

Delete the repository folder located inside the .m2 directory.

Or, using PowerShell:

# This command will permanently delete your local Maven artifact cache
Remove-Item -Recurse -Force "$env:USERPROFILE\.m2\repository"

4. Invalidate Caches in Android Studio / IntelliJ IDEA

After clearing the build tool caches, the final step is to clear the IDE's own caches. The IDE maintains its own set of caches for project indexing, the virtual file system, and local history to speed up operations. Sometimes these caches can get out of sync with the actual state of the project files.

When to use "Invalidate Caches"

• After major branch changes: If you switch between branches with significantly different dependency trees.
• When the IDE shows errors but the command line build succeeds: This is a classic sign of a desynchronized IDE cache.
• After upgrading the IDE or major plugins.
• As a final step after manually clearing the .gradle and .m2 folders, as we are doing in this guide.

How to Invalidate Caches

1. Open your project in Android Studio or IntelliJ IDEA.
2. Go to File in the top menu bar.
3. Click on Invalidate Caches....
4. A dialog box will appear with several options. For a complete cleanup, it's recommended to select all available checkboxes:
   • Clear file system cache and Local History: This removes the caches for the virtual file system and your local revision history.
   • Clear VCS Log caches and indexes: This clears caches related to your version control system (e.g., Git).
   • Ask before downloading new shared indexes: You can leave this checked.
5. Click the Invalidate and Restart button.

The IDE will shut down, clear its caches, and then restart. Upon restarting, it will need to re-index your entire project from scratch. This process can be slow, especially for large projects, but it ensures the IDE has a completely fresh view of your code and dependencies.

5. The Final Build

After completing all the steps above, open your project. Let the IDE finish its indexing. Then, run your first build. Gradle will re-download all dependencies, and both your build tools and IDE will be operating from a completely clean state.

To be absolutely certain you are not using any locally resolved dependencies, you can add the --refresh-dependencies flag to your first build command:

./gradlew build --refresh-dependencies