skip to content

How do you pin the distribution checksum using the wrapper task instead of editing gradle-wrapper.properties by hand?

level: middleimportance: must knowfreq 40%

answer

  1. wrapper task + --gradle-distribution-sha256-sum
  2. combine with --gradle-version
  3. sum differs per version AND bin/all type
  4. writes distributionSha256Sum line
  5. tasks.wrapper { distributionSha256Sum = ... } equivalent

basics

~10 s

Run the wrapper task with --gradle-distribution-sha256-sum and the official checksum, e.g. ./gradlew wrapper --gradle-version 8.7 --gradle-distribution-sha256-sum <sum>. Gradle writes distributionSha256Sum into gradle-wrapper.properties for you.

solid answer

~30 s

Use the built-in `wrapper` task with the `--gradle-distribution-sha256-sum` option. You pass the SHA-256 that Gradle publishes for the target distribution, and Gradle writes (or updates) the `distributionSha256Sum` line in `gradle/wrapper/gradle-wrapper.properties`. Typically you combine it with `--gradle-version` (and optionally `--distribution-type bin|all`) so the URL and the pinned sum stay consistent in one operation: ```bash ./gradlew wrapper --gradle-version 8.7 \ --gradle-distribution-sha256-sum 544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d ``` Doing it via the task (rather than hand-editing) avoids copy-paste errors and keeps `distributionUrl` and the sum in sync. You then commit the updated `gradle-wrapper.properties`. The next wrapper run verifies the download against the pinned value.

code

bash · 5 lines
bash
./gradlew wrapper \
  --gradle-version 8.7 \
  --distribution-type bin \
  --gradle-distribution-sha256-sum 544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d
# regenerates gradle-wrapper.properties with both distributionUrl and distributionSha256Sum

go deeper

for a junior

Know the wrapper task plus the --gradle-distribution-sha256-sum flag writes the property.

for a middle

Combine it with --gradle-version, know the sum is per-version-and-type, and commit the result.

for a senior

Explain the build-script Wrapper task equivalent and why task-driven pinning avoids drift between URL and sum.

for a principal

Standardize the upgrade procedure (script the wrapper-bump + sum pin) so version upgrades can't land an unpinned or mismatched distribution.

## The wrapper task Gradle ships a built-in task named `wrapper` that regenerates the wrapper files: the scripts, `gradle-wrapper.jar`, and `gradle-wrapper.properties`. It accepts command-line options that control what gets written. ## Pinning the checksum The relevant option is `--gradle-distribution-sha256-sum`. You give it the SHA-256 string that Gradle officially publishes for the distribution you're targeting, and the task writes a `distributionSha256Sum=<value>` line into `gradle-wrapper.properties`. ```bash ./gradlew wrapper \ --gradle-version 8.7 \ --distribution-type all \ --gradle-distribution-sha256-sum cb87f222c5585bd46838ad4db78463a5c5f3d336e5e2b98dc7c0c586527351c2 ``` - `--gradle-version` sets `distributionUrl` to the matching version, so the sum and URL are pinned together in one step. - `--distribution-type bin|all` picks `-bin.zip` vs `-all.zip`; **the published sum differs per distribution type and version**, so you must use the sum that matches the exact archive your URL points to. ## Why this beats hand-editing Hand-pasting a 64-hex-char checksum is error-prone, and it's easy to update the version but forget to update the sum (or vice-versa), which makes builds fail mysteriously or, worse, silently keep an old unverified URL. Running the task keeps the two consistent and is reproducible/scriptable in CI. ## Equivalent build-script configuration You can also configure the `Wrapper` task type in a build script: ```kotlin tasks.wrapper { gradleVersion = "8.7" distributionType = Wrapper.DistributionType.ALL // distributionSha256Sum can be set here too distributionSha256Sum = "cb87f222c5585bd46838ad4db78463a5c5f3d336e5e2b98dc7c0c586527351c2" } ``` ## After pinning Commit the regenerated `gradle-wrapper.properties`. On the next run the wrapper downloads the distribution (if not cached) and verifies its SHA-256 against the pinned value before executing.

  • Why must the sum match the distribution type (bin vs all)?
    Gradle publishes a different SHA-256 for -bin.zip and -all.zip of the same version. The wrapper verifies the exact archive your distributionUrl downloads, so a bin sum will fail against an all archive.
  • Can you set the sum in a build script instead of the CLI?
    Yes — configure tasks.wrapper { distributionSha256Sum = "..." } on the Wrapper task type; running the wrapper task then writes it into gradle-wrapper.properties.
  • Do you need to run the task twice for the pin to take effect?
    There's a known gotcha: regenerating the wrapper may run with the old distribution. Run it once to update the properties, commit, then the next invocation verifies against the new pinned sum.

  • Pasting a sum that doesn't match the chosen distribution type or version.
  • Updating --gradle-version but leaving a stale distributionSha256Sum.
  • Inventing/guessing the checksum instead of using the official published value.

context