skip to content

If you register no toolchain repositories, or want to forbid downloads entirely, how does Gradle behave and how do you control auto-download independently of toolchainManagement?

level: middleimportance: should knowfreq 25%

answer

  1. two knobs: source vs permission
  2. empty javaRepositories = no source
  3. auto-download property gates downloads
  4. false = local JDKs only
  5. hermetic/offline CI use case

basics

~10 s

With no repository registered, Gradle can't download a missing JDK and fails if it can't find one locally. You can also globally disable downloads with the property org.gradle.java.installations.auto-download=false.

solid answer

~40 s

Two separate switches govern provisioning. The `toolchainManagement` block decides *where* JDKs may come from — with **no** repository registered, Gradle has no source and will fail when a requested toolchain isn't found among locally detected installations. Separately, the property `org.gradle.java.installations.auto-download=false` (in `gradle.properties` or `-P`/`-D`) turns auto-download **off** regardless of registered repositories, forcing Gradle to use only local JDKs. The two compose: registering a repository enables a source, the property gates whether downloads are attempted at all. To require BYO-JDK builds (CI provides the JDK, no network downloads), set the property to false even if a resolver happens to be on the classpath.

code

bash · 6 lines
bash
# Force local-only toolchain resolution for this build (no downloads)
./gradlew build -Porg.gradle.java.installations.auto-download=false

# Or persist it:
# gradle.properties
#   org.gradle.java.installations.auto-download=false

go deeper

for a junior

Know that without a registered repository Gradle can't download a missing JDK and the build fails.

for a middle

Distinguish the repository (source) from the auto-download property (permission) and give the failure modes.

for a senior

Explain hermetic-CI setups: internal resolver for devs plus auto-download=false on CI to fail fast.

for a principal

Set org policy: enforce auto-download=false in CI base configs, pre-provision approved JDKs, block public download endpoints at the network layer.

## Two independent controls Newcomers conflate them, but provisioning has two orthogonal knobs: ### 1. Repositories — the *source* (toolchainManagement) `toolchainManagement { jvm { javaRepositories { ... } } }` declares which resolvers may supply a JDK. With an **empty** list (or no block at all), there is no source, so a download cannot happen. A request for a missing toolchain then fails with a message that no matching toolchain was found and none could be provisioned. ### 2. auto-download — the *permission* (a property) ```properties # gradle.properties org.gradle.java.installations.auto-download=false ``` This is a build property, **not** part of the `toolchainManagement` DSL. When false, Gradle never attempts a download even if resolvers are registered — it relies solely on locally detected JDKs (from `org.gradle.java.installations.paths`, auto-detection, etc.). When true (default) and a repository is registered, missing toolchains are downloaded. ## Truth table | Repository registered? | auto-download | Missing toolchain → | |---|---|---| | no | true | fail (no source) | | no | false | fail (no source, no download anyway) | | yes | true | download from resolver | | yes | false | do not download; fail if not found locally | ## Why disable downloads - **Hermetic/offline CI**: agents pre-install approved JDKs; network egress to download tools is blocked or undesirable. - **Reproducibility/governance**: you want builds to fail loudly if the expected JDK isn't present rather than silently pulling one. - **Speed**: avoid first-build download latency when the JDK is guaranteed present. ## Practical pairing A common hardened setup: register only an internal resolver in `toolchainManagement` for developer convenience, but set `auto-download=false` on CI so CI never downloads and instead consumes a pre-provisioned JDK — surfacing misconfiguration immediately.

  • Does setting auto-download=false remove the need for toolchainManagement repositories?
    They are independent. auto-download=false means Gradle never downloads regardless of registered repos; it just uses local JDKs. Repositories only matter when downloads are permitted.
  • Where does Gradle look for local JDKs when downloads are disabled?
    Auto-detected installations plus any paths listed in org.gradle.java.installations.paths, environment variables like JAVA_HOME, and standard SDK locations. If none match the spec, the build fails.

saying these in an interview costs you the question

  • Saying you disable downloads by removing the toolchainManagement block — that removes the source but the proper kill-switch is the auto-download property.
  • Treating auto-download as part of the toolchainManagement DSL; it's a gradle.properties property.

context

resolving links…