skip to content

How do you configure the `Wrapper` task type declaratively in build.gradle.kts instead of passing CLI flags each time?

level: middleimportance: should knowfreq 35%

answer

  1. tasks.wrapper { gradleVersion = ... }
  2. Wrapper.DistributionType.ALL
  3. distributionUrl for internal mirror
  4. CLI flags override script config
  5. self-documenting version in VCS

basics

~10 s

Configure the built-in wrapper task in your build script: set gradleVersion, distributionType, and optionally distributionUrl/networkTimeout. Then ./gradlew wrapper regenerates files using those values without repeating CLI flags.

solid answer

~40 s

Gradle's `wrapper` task is an instance of `Wrapper`, and you can configure it declaratively so the desired version and options live in version control. In Kotlin DSL you write `tasks.wrapper { gradleVersion = "9.0"; distributionType = Wrapper.DistributionType.ALL }`. Now anyone running `./gradlew wrapper` regenerates the wrapper to those settings — no need to remember `--gradle-version`/`--distribution-type`. Useful properties include `gradleVersion`, `distributionType`, `distributionUrl` (a fully custom URL, e.g. an internal mirror), `distributionSha256Sum` (verification), `networkTimeout`, and the script/jar file paths. CLI flags, when supplied, override the configured values for that invocation. This declarative approach documents the intended Gradle version in the build itself and makes upgrades a one-line edit plus a task run.

code

kotlin · 8 lines
kotlin
// build.gradle.kts — declare the wrapper's settings in source control
tasks.wrapper {
    gradleVersion = "9.0"
    distributionType = Wrapper.DistributionType.ALL
    networkTimeout = 30_000
}

// Then simply:  ./gradlew wrapper   (no flags needed)

go deeper

for a junior

Know the wrapper task can be configured with gradleVersion in the build script.

for a middle

Show the tasks.wrapper { } block, name distributionType/distributionUrl, and that CLI flags override.

for a senior

Discuss using distributionUrl for internal mirrors/air-gapped setups and keeping the version self-documenting and reviewable.

for a principal

Standardize a shared convention (mirror, pinned version, timeout) across many repos, possibly via a convention plugin.

## The `wrapper` task is configurable The built-in `wrapper` task is an instance of `org.gradle.api.tasks.wrapper.Wrapper`. Like any Gradle task you can configure it in your build script, which lets you encode the intended Gradle version and wrapper options in source control rather than relying on people remembering CLI flags. ## Kotlin DSL configuration ```kotlin tasks.wrapper { gradleVersion = "9.0" distributionType = Wrapper.DistributionType.ALL // optional extras networkTimeout = 30_000 // distributionUrl = "https://mirror.example.com/gradle-9.0-all.zip" // internal mirror } ``` With that in place, `./gradlew wrapper` regenerates the wrapper files using exactly these values. ## Key properties - **`gradleVersion`** — the target version; Gradle derives the standard `distributionUrl` from it. - **`distributionType`** — `Wrapper.DistributionType.BIN` or `ALL`. - **`distributionUrl`** — a fully explicit URL, overriding the derived one; handy for internal mirrors or air-gapped networks. - **`networkTimeout`** — download timeout in milliseconds. - **`scriptFile` / `jarFile`** — customize where `gradlew` and the bootstrap jar are written (rarely needed). ## CLI flags override configuration When you pass `--gradle-version` or `--distribution-type` on the command line, those override the script-configured values for that single run. So the script is the default, and flags are an ad-hoc override. ## Why declarative is nicer - The intended Gradle version is **self-documenting** in `build.gradle.kts`. - Upgrades become a reviewable one-line diff plus `./gradlew wrapper`. - Pointing the whole team at an internal mirror is a single config change. ## A subtlety Configuring `gradleVersion` in the script changes what the `wrapper` task *generates*; it does **not** change the version the *current* invocation runs under. You still run the task (under the old version) to write the new files, then commit them — exactly as with the CLI flag.

  • If both the script sets `gradleVersion = "9.0"` and you pass `--gradle-version 8.14`, which wins?
    The CLI flag wins for that invocation; `--gradle-version 8.14` overrides the script's configured value just for that run.
  • When would you set `distributionUrl` explicitly instead of `gradleVersion`?
    When you must download from an internal mirror or an air-gapped/corporate artifact host. `distributionUrl` lets you point at any URL, overriding the standard `services.gradle.org` location Gradle would otherwise derive.

saying these in an interview costs you the question

  • Believing configuring `gradleVersion` changes the version the current build runs under (it only affects what the task generates).
  • Thinking script config can't be overridden — CLI flags still take precedence per-run.
  • Putting the version only in CI scripts instead of the build, losing the self-documenting benefit.

context

resolving links…