skip to content

What does the org.gradle.parallel flag do, and how do you enable it both persistently and for a single build invocation?

level: juniorimportance: must knowfreq 70%

answer

  1. parallel = across different projects
  2. bounded by org.gradle.workers.max
  3. requires decoupled projects
  4. --parallel / --no-parallel
  5. no help for single-project builds

basics

~10 s

org.gradle.parallel=true lets Gradle run tasks from different projects at the same time using worker threads. Set it in gradle.properties, or pass --parallel on the command line for one build.

solid answer

~30 s

`org.gradle.parallel` enables **project-level parallel execution**: Gradle runs tasks belonging to *different* projects concurrently, bounded by `org.gradle.workers.max` (defaults to the number of CPU cores). It only helps multi-project builds and requires projects to be **decoupled** — no cross-project configuration access at execution time, or you risk incorrect results. Enable it persistently in `gradle.properties` with `org.gradle.parallel=true`, or for one invocation pass `--parallel` on the CLI (and `--no-parallel` to override a persistent setting). Tasks *within* a single project still run sequentially in dependency order. It pairs well with `org.gradle.caching` and the configuration cache for large monorepos.

code

properties · 2 lines
properties
org.gradle.parallel=true
org.gradle.workers.max=8

go deeper

for a junior

Know it runs different projects' tasks concurrently and how to set it in gradle.properties or via --parallel.

for a middle

Explain the worker-max cap, that it only helps multi-project builds, and the --no-parallel override.

for a senior

Discuss the decoupled-projects requirement, failure modes from coupling, and pairing with caching + configuration cache.

for a principal

Frame an org-wide rollout: enforce decoupling via configuration cache, standardize workers.max in CI, and measure throughput before/after.

## What it controls `org.gradle.parallel` turns on **parallel project execution**. By default Gradle executes the task graph one task at a time. With parallelism on, Gradle can run tasks from *different* projects (subprojects) simultaneously, each in its own worker, while respecting task dependencies across the whole graph. ## The worker pool The degree of concurrency is capped by `org.gradle.workers.max`. If unset it defaults to the number of available processors. This same pool is shared with the Worker API and other parallel work, so it is a global concurrency budget, not a per-feature one. ## Decoupled projects requirement Parallel execution is only safe when projects are **decoupled**: at execution time one project must not reach into another project's mutable state (e.g. `project(':other').someTask.outputs`, or modifying another project's tasks/configurations during execution). Coupled projects can produce nondeterministic or wrong builds. The configuration cache enforces decoupling, which is why the two features are often adopted together. ## Scope of the speedup Parallelism helps **multi-project** builds. A single-project build sees no benefit, because tasks within one project are not run in parallel by this flag (test/work parallelism is separate, e.g. JUnit forks or the Worker API). ## Persistent vs per-invocation - Persistent: add `org.gradle.parallel=true` to the project's `gradle.properties` (or the user-level `~/.gradle/gradle.properties`). - Per-invocation: pass `--parallel`. To disable for one run when it is persistently on, pass `--no-parallel`. ```properties # gradle.properties org.gradle.parallel=true org.gradle.workers.max=8 ``` ```bash # one-off, overriding a persistent setting ./gradlew build --no-parallel ``` ## Interaction with other flags Parallel execution composes with `org.gradle.caching` (each task can still pull from the build cache) and the configuration cache (which parallelizes configuration too). Treat the three as the standard performance trio for large builds.

  • Will org.gradle.parallel speed up a single-module project?
    No. It only parallelizes tasks across different projects. A single-project build runs its tasks sequentially regardless; parallelism there must come from elsewhere (e.g. test forking or the Worker API).
  • What property caps the number of parallel workers?
    org.gradle.workers.max. It defaults to the number of CPU cores and is a shared budget for parallel execution and the Worker API.

Like assembling several independent IKEA cabinets at once with a crew, instead of one person finishing one cabinet before starting the next — but only works if no cabinet borrows parts from another mid-assembly.

saying these in an interview costs you the question

  • Claiming it parallelizes tasks within the same project.
  • Saying it is always safe — it requires decoupled projects or results can be wrong.
  • Confusing it with test-level parallelism (maxParallelForks).

context

resolving links…