The Gradle Wrapper: What It Is and Why to Use It

The Gradle wrapper solves the build tool version consistency problem — without it, every developer and CI agent runs whatever version of Gradle they have installed locally, and version mismatches cause builds that work on one machine and fail on another.

What the wrapper does

• The wrapper commits a shell script (gradlew) and a properties file (gradle/wrapper/gradle-wrapper.properties) declaring the exact Gradle version the project uses
• Running ./gradlew build automatically downloads that version if it is not already cached locally — every developer and every CI agent gets the same binary without manual installation
• The wrapper files are small (a few KB) and should be committed to version control — they are the project's contract with the Gradle version

Security and upgrade

• Add distributionSha256Sum to the properties file to verify the download integrity — without it, a compromised download mirror could substitute a malicious Gradle binary
• Upgrading is a single command: ./gradlew wrapper --gradle-version 8.6 updates the properties file; commit the change and the entire team and CI pick it up automatically on the next build
• Always call ./gradlew, never bare gradle — add a CI lint step that rejects any pipeline script using the system gradle command to prevent accidental version drift in automated environments

Wrapper in CI

• CI agents do not need Gradle pre-installed — the wrapper handles it; this simplifies CI image management and ensures every project uses its declared version regardless of what other projects on the same agent use