skip to content

Explain the difference between `maxParallelForks` on a Test task and the `org.gradle.parallel` build flag. Do they interact?

level: seniorimportance: should knowfreq 40%

answer

  1. org.gradle.parallel = tasks across projects
  2. maxParallelForks = classes within one Test task
  3. both draw on --max-workers global cap
  4. demand ≈ parallel modules × forks
  5. tune together to fit cores/RAM

basics

~20 s

maxParallelForks parallelises test classes within one Test task across multiple JVMs. org.gradle.parallel=true parallelises tasks across projects (e.g. two modules' tests run together). Both draw on the same --max-workers pool, so they compete for that global worker budget.

solid answer

~50 s

They operate at different layers: - **`org.gradle.parallel`** (build-level): lets Gradle execute tasks from *different projects* concurrently when their dependencies allow — so `:moduleA:test` and `:moduleB:compileJava` can run at once. It's about the **task graph**. - **`maxParallelForks`** (Test-task-level): within a *single* Test task, runs test classes across N concurrent forked JVMs. It's about **one task's internal work**. They interact through a shared resource: **`--max-workers` / `org.gradle.workers.max`** is the daemon-wide cap on concurrent worker processes, and *both* mechanisms draw from it. If module A and module B both run tests in parallel (project parallelism), and each test task has `maxParallelForks = 4`, you could demand 8 forks plus other tasks — all bounded by `--max-workers`. Over-subscribing causes memory pressure. So tune them together: in a big multi-module build, modest per-task forks plus project parallelism, with `--max-workers` sized to the machine.

code

toml · 4 lines
toml
# gradle.properties
org.gradle.parallel=true      # run tasks across projects concurrently
org.gradle.workers.max=8      # global cap shared by ALL parallel work
# (maxParallelForks is set per Test task in build logic and is bounded by the cap above)

go deeper

for a junior

Not deeply expected; at most know they're different settings, one for the build, one for tests.

for a middle

Clearly distinguish project-graph parallelism from within-Test-task forking and know maxParallelForks works independently of org.gradle.parallel.

for a senior

Explain the shared --max-workers budget, the multiplicative resource demand, and how to tune the two together for a multi-module build/CI.

for a principal

Define build-wide parallelism policy across many modules and CI agents, balancing throughput against memory and reproducibility under the global worker cap.

## Two layers of parallelism Gradle parallelism exists at multiple, independent layers. Confusing them is a classic interview trap. ### Layer 1 — `org.gradle.parallel` (task/project graph) Set in `gradle.properties`: ```properties org.gradle.parallel=true ``` This tells Gradle it may run tasks from **different projects** concurrently, as long as the task dependency graph permits (no ordering/produces-consumes conflict). In a multi-module build, `:serviceA:test` and `:serviceB:test` can then run simultaneously. It does **nothing** inside a single task. ### Layer 2 — `maxParallelForks` (inside one Test task) This splits the work of **one** Test task across multiple forked JVMs, distributing test *classes* among them. It's local to that task and unrelated to how many projects you have. ### (There's also engine-level, method parallelism — JUnit 5's `junit.jupiter.execution.parallel.enabled` — a third, in-JVM layer. Not the question here, but worth distinguishing.) ## The shared budget: --max-workers The glue is the **global worker cap**: ```properties org.gradle.workers.max=8 ``` or `--max-workers=8` on the CLI. This bounds the **total** number of worker processes the daemon runs concurrently — and *both* layers consume from it. A test fork is a worker; a parallel project task is a worker. Consequence: with project parallelism on, two modules running tests, each `maxParallelForks = 4`, want 8 test forks at once — plus any other parallel tasks — all squeezed under `--max-workers`. If the cap is lower, Gradle serialises some of it; if the cap is high but the machine is small, you OOM. ## Tuning them together ```properties # gradle.properties org.gradle.parallel=true org.gradle.workers.max=8 ``` ```kotlin // build logic — keep per-task forks modest so cross-module parallelism fits tasks.withType<Test>().configureEach { maxParallelForks = 2 } ``` Rule of thumb: total demand ≈ (parallel modules running tests) × maxParallelForks. Keep that, plus memory per fork, within the machine. In CI, sizing `--max-workers` and per-task forks to the agent's cores/RAM gives reproducible throughput. ## Summary table | Mechanism | Scope | Unit parallelised | |---|---|---| | `org.gradle.parallel` | whole build | tasks across projects | | `maxParallelForks` | one Test task | test classes (forked JVMs) | | `--max-workers` | daemon | caps total workers (shared) |

  • If org.gradle.parallel is off, does maxParallelForks still work?
    Yes. maxParallelForks parallelises classes inside a single Test task regardless of project-level parallelism; the two flags are independent.
  • Why can the two together cause OOM even with reasonable individual settings?
    Because demand multiplies: parallel modules each forking N test JVMs can request many forks at once, all drawing on --max-workers. The combined memory of all live forks must still fit the machine.
  • Where does --max-workers fit in?
    It's the daemon-wide cap on concurrent worker processes. Both project parallelism and test forks consume from this single budget, so it ultimately bounds both.

  • Claiming org.gradle.parallel speeds up tests within one task — it parallelises tasks across projects.
  • Treating maxParallelForks and org.gradle.parallel as the same setting.
  • Ignoring that both share the --max-workers budget when reasoning about resource use.

context