skip to content

How do you enable parallel project execution in Gradle, and what exactly does it parallelize?

level: juniorimportance: must knowfreq 70%

answer

  1. --parallel flag / org.gradle.parallel=true
  2. tasks across DIFFERENT projects run concurrently
  3. within a project still sequential
  4. off by default
  5. needs decoupled projects

basics

~10 s

Pass --parallel on the command line, or set org.gradle.parallel=true in gradle.properties. Gradle then runs tasks from different projects concurrently using the daemon's worker threads, instead of one project at a time.

solid answer

~40 s

Parallel execution runs **tasks belonging to different projects** at the same time. You turn it on per-invocation with `--parallel`, or persistently by putting `org.gradle.parallel=true` in `gradle.properties` (project root or `~/.gradle`). It is off by default. Under the hood the daemon maintains a pool of worker leases (size = `org.gradle.workers.max`, defaulting to CPU count) and schedules ready tasks across projects onto that pool. Tasks *within a single project* still run sequentially in declared/dependency order — the win comes from independent modules building at once. The main prerequisite is that projects are **decoupled**: no project may reach into another project's model at execution time. The execution phase is parallelized; configuration is not (that needs configuration-on-demand or the configuration cache).

code

bash · 5 lines
bash
# one-off
./gradlew build --parallel

# persistent: gradle.properties
org.gradle.parallel=true

go deeper

for a junior

Know the flag and the property, and that it runs different modules at the same time.

for a middle

Explain the worker-lease pool, workers.max default, and that within-project tasks stay sequential.

for a senior

Tie it to the decoupled-projects requirement and how the task graph still enforces ordering across modules.

for a principal

Discuss rolling it out org-wide via init scripts / shared gradle.properties and the trade-offs vs configuration cache and remote build cache.

## What parallel execution does A Gradle build is a tree of *projects* (modules). By default Gradle executes the tasks of one project, then the next, in a single sweep. **Parallel project execution** lets Gradle run tasks from *different* projects simultaneously, which shortens wall-clock time on multi-module builds. It is **disabled by default**. Enable it two ways: - Command line: `./gradlew build --parallel` - Persistent: add `org.gradle.parallel=true` to `gradle.properties` (in the project root, or in `~/.gradle/gradle.properties` to apply to all builds). ## What is and isn't parallelized - **Across projects:** `:moduleA:compileJava` and `:moduleB:compileJava` can run at the same time if neither depends on the other. - **Within a project:** tasks still run sequentially, ordered by their dependency graph. - **Configuration phase:** *not* parallelized by this flag — every project is still configured (unless you also enable configuration-on-demand or the configuration cache). ## The worker-lease model The daemon holds a fixed number of *worker leases*, controlled by `org.gradle.workers.max` (default = number of CPU cores). Each running task occupies one lease. Gradle's scheduler walks the merged task graph, finds tasks whose dependencies are satisfied, and dispatches as many as there are free leases. This same lease pool is shared with the Worker API, so CPU-bound work doesn't oversubscribe the machine. ## The hard requirement: decoupled projects Tasks can only run concurrently if the projects are **decoupled** — a project must never directly access the mutable state (tasks, configurations, extensions, properties) of another project during configuration or execution. Cross-project wiring must go through proper dependencies (`project(":other")`) or lazy providers, not `project(":other").tasks.getByName(...).someValue` at execution time. Violating this can produce nondeterministic results or warnings. ```kotlin // gradle.properties // org.gradle.parallel=true // org.gradle.workers.max=8 ``` The net effect: independent modules compile, test, and jar concurrently, while dependency edges still force the correct ordering.

  • Does --parallel parallelize tasks within a single project?
    No. Tasks inside one project still run sequentially according to their dependency order; only tasks from different (decoupled) projects run concurrently.
  • What controls how many tasks run at once?
    org.gradle.workers.max (default = CPU core count). It sizes the daemon's worker-lease pool, which is shared with the Worker API.

saying these in an interview costs you the question

  • Claiming it's on by default — it is off by default.
  • Saying it parallelizes the configuration phase — it does not.
  • Confusing it with the Worker API (intra-task parallelism).

context

resolving links…