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.

saying these in an interview costs you the question

  • 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

resolving links…