How to Cache the .gradle Directory in GitHub Actions

A fresh runner re-downloads every Gradle dependency and wrapper distribution unless the Gradle home is cached.

The official gradle/actions/setup-gradle action caches ~/.gradle/caches and the wrapper for you; you can also cache it manually keyed on your build scripts.

Steps

• Set up the JDK with actions/setup-java.
• Add gradle/actions/setup-gradle to enable dependency and configuration caching.
• For a manual approach, cache ~/.gradle/caches and ~/.gradle/wrapper.
• Key on hashFiles of *.gradle* and gradle-wrapper.properties.

Workflow

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
      - uses: gradle/actions/setup-gradle@v4
      - run: ./gradlew build --build-cache

Gotchas

• Pass --build-cache so Gradle actually reuses task outputs, not just downloaded jars.
• Avoid caching ~/.gradle wholesale; daemon logs and locks bloat the cache.
• Latchkey keeps the Gradle home warm across jobs so JVM builds start fast and retry transient failures.

Related guides