Introduction

Checking the Gradle version looks straightforward, but teams often waste time because they check the wrong installation. A machine can have a global gradle command on the PATH and a project-specific Gradle Wrapper pinned inside the repository, and those versions do not have to match. In most real projects, the wrapper version is the one that matters.

If your build behaves differently on a laptop and in CI, start by answering two separate questions: “Which Gradle version does this repository declare?” and “Which Gradle version am I actually running right now?”

Use the Wrapper Before the Global Command

The fastest check inside a project is:

./gradlew --version

On Windows, the equivalent is:

gradlew.bat --version

This reports the version configured by the Gradle Wrapper for that repository. In a shared codebase, that is usually the source of truth because everyone can run the same build without managing local installations manually.

You can still inspect the system-wide Gradle on your PATH:

gradle --version

That command is useful when you intentionally rely on a global installation, but it is often the wrong answer for team-managed builds. If gradle --version and ./gradlew --version differ, trust the wrapper unless you have a very specific reason not to.

Read the Wrapper Properties File

You do not need to execute Gradle to find the pinned version. The wrapper configuration lives in gradle/wrapper/gradle-wrapper.properties, and the distributionUrl value contains the version number.

sed -n '1,80p' gradle/wrapper/gradle-wrapper.properties

A typical entry looks like this:

distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.0-bin.zip

From that line, you can see the wrapper is pinned to 9.3.0. This check is handy when reviewing a repository, debugging CI, or reading a codebase where the wrapper has not been downloaded yet.

The wrapper file is especially important because it is committed to version control. That means it defines the build version intended by the project, not just by one developer machine.

Check Java at the Same Time

Many “Gradle version” problems are really Java compatibility problems. A better debugging habit is to print both:

./gradlew --version
java -version

The Gradle version output also shows JVM details, Kotlin, Groovy, and operating-system information. That context matters because plugin compatibility often depends on both Gradle and Java.

If a colleague says “the project is on Gradle 9,” that still does not tell you whether they are running it with a supported JDK. Build failures that look like Gradle issues often come from mismatched Java installations or CI images.

Make the Version Visible in CI

If you support a build pipeline, print the wrapper version early so logs tell you exactly what ran.

1name: build
2on: [push]
3
4jobs:
5  test:
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v4
9      - uses: actions/setup-java@v4
10        with:
11          distribution: temurin
12          java-version: '21'
13      - name: Show Gradle version
14        run: ./gradlew --version

This adds almost no cost, and it removes guesswork when a pipeline starts failing after a wrapper upgrade or base-image change.

Upgrade the Wrapper Intentionally

When you want to change versions, update the wrapper rather than telling every developer to install a different global Gradle.

./gradlew wrapper --gradle-version 9.3.0
./gradlew --version

After that, review the wrapper files in Git:

git diff gradle/wrapper/gradle-wrapper.properties gradlew gradlew.bat

This keeps the upgrade reviewable and reproducible. It also means CI and local development stay aligned.

If you ever edit gradle-wrapper.properties manually, use a full release number rather than a shortened major version. The wrapper configuration should point to an exact distribution.

Common Pitfalls

The most common mistake is running gradle --version and assuming that tells you the version the repository build uses. In many projects, it does not.

Another mistake is checking only Gradle and ignoring Java. The wrapper may be correct while the actual JDK makes the build fail.

A third problem is updating the wrapper locally but forgetting to commit the changed wrapper files, which leaves teammates and CI on the previous version.

Summary

• Use ./gradlew --version as the main version check inside a project.
• Treat gradle --version as a check for the global installation, not automatically for the repository.
• Read gradle/wrapper/gradle-wrapper.properties to confirm the pinned distribution version.
• Check Java and Gradle together when debugging environment issues.
• Upgrade Gradle through the wrapper and commit the wrapper-related file changes.