skip to content

When multiple init scripts apply at once, in what order does Gradle run them, and why can that ordering matter?

level: seniorimportance: nice to knowfreq 25%

answer

  1. all applied, order = precedence
  2. --init-script first (cmd-line order)
  3. then init.gradle(.kts)
  4. then init.d/ alphabetically
  5. number-prefix filenames for determinism

basics

~20 s

Gradle applies init scripts in a fixed order: --init-script files (in command-line order), then ~/.gradle/init.gradle(.kts), then ~/.gradle/init.d/ files alphabetically, then the distribution's init.d/. Order matters when later scripts override repositories or settings set by earlier ones.

solid answer

~40 s

All discovered init scripts are applied, in a defined order: (1) every file passed via `--init-script`, in the order given on the command line; (2) `USER_HOME/.gradle/init.gradle` (or `.gradle.kts`); (3) each `.gradle`/`.gradle.kts` in `USER_HOME/.gradle/init.d/`, **alphabetically by filename**; (4) each script in the Gradle distribution's `init.d/`. Because they all run, the ordering is about *precedence when they touch the same thing* — e.g. two scripts both clearing-and-setting `allprojects` repositories, or one registering a `beforeProject` listener that another depends on. The common convention is to **prefix init.d filenames with numbers** (`00-`, `10-`, `99-`) to make the alphabetical order explicit and deterministic. If the only `~/.gradle/init.gradle` exists, Gradle uses it; note that a single canonical `init.gradle` is mutually exclusive in name (you can't have both `init.gradle` and `init.gradle.kts` causing ambiguity), but `init.d/` files are always additive.

code

bash · 5 lines
bash
# numeric prefixes make init.d order deterministic
ls ~/.gradle/init.d/
# 00-logging.init.gradle.kts
# 10-repositories.init.gradle.kts
# 99-policy.init.gradle.kts   <- runs last, can override the rest

go deeper

for a junior

Know that more than one init script can apply and init.d files are read alphabetically.

for a middle

State the full source order and why numeric filename prefixes are used.

for a senior

Reason about precedence when scripts mutate the same config and design deterministic ordering.

for a principal

Set org conventions (numeric prefixes, single-purpose scripts, --init-script baselines) so fleet ordering is predictable and auditable.

## They're additive, then ordered A frequent misconception is that one init-script source "wins". In reality Gradle **applies every** init script it finds; the order only decides who runs first when two scripts configure the same thing. ## The exact application order 1. **`--init-script` / `-I` files** — applied in the left-to-right order they appear on the command line. 2. **`USER_HOME/.gradle/init.gradle` or `init.gradle.kts`** — the single canonical user init script. 3. **`USER_HOME/.gradle/init.d/*.gradle` and `*.gradle.kts`** — every script in the directory, sorted **alphabetically by filename**. 4. **`<distribution>/init.d/*`** — scripts bundled in the Gradle distribution. `USER_HOME` is the Gradle user home (`~/.gradle` unless overridden by `-g`/`GRADLE_USER_HOME`). ## Why the order can bite you Suppose one init script in `init.d/` does `allprojects { repositories { mavenCentral() } }` and another later one does `allprojects { repositories { clear(); maven { url = mirror } } }`. The second runs after the first (alphabetically later filename), so its `clear()` wins and the mirror replaces Central. Reverse the filenames and you get the opposite behavior. Listener registration order (`beforeProject`, `settingsEvaluated`) is also preserved, so a logging hook registered first fires before one registered later. ## The naming convention Because `init.d/` ordering is alphabetical, teams prefix filenames with a numeric segment to control sequence deterministically: ``` ~/.gradle/init.d/ 00-logging.init.gradle.kts # runs first 10-repositories.init.gradle.kts 20-credentials.init.gradle.kts 99-policy-enforcement.init.gradle.kts # runs last ``` This is the same idea as `/etc/*.d` directories on Unix. ## Practical guidance - Don't rely on accidental alphabetical order — name files with explicit numeric prefixes. - Remember `--init-script` files run *before* anything in `init.d/`, so a CI-passed script can set a baseline that user-home scripts then extend. - Keep each init script single-purpose so ordering interactions stay obvious.

  • If init.d/10-repos sets a repository and init.d/20-repos clears and replaces it, which wins?
    20-repos, because init.d files run alphabetically and 20 sorts after 10, so its clear/replace runs last and takes precedence.
  • Do --init-script files run before or after ~/.gradle/init.d scripts?
    Before. Command-line --init-script files are applied first, then the user init.gradle, then init.d, then the distribution's init.d.

saying these in an interview costs you the question

  • Saying only one init script is chosen and the rest ignored — all are applied.
  • Assuming init.d order is random or by mtime; it's alphabetical by filename.

context

resolving links…