gradle --parallel: Build Projects Concurrently
gradle --parallel runs tasks from independent subprojects at the same time, using up to --max-workers worker processes.
On a multi-module build with idle cores, --parallel is the easiest speedup. It only helps when subprojects are decoupled enough to run side by side.
What it does
With --parallel, Gradle executes tasks from different subprojects concurrently, respecting task dependencies. --max-workers caps the number of concurrent workers (defaulting to the number of processors). It has no effect on a single-module build.
Common usage
./gradlew build --parallel
./gradlew build --parallel --max-workers=4
# enable by default
echo "org.gradle.parallel=true" >> gradle.propertiesFlags
| Flag / property | What it does |
|---|---|
| --parallel | Run independent subprojects concurrently |
| --max-workers=N | Cap concurrent workers |
| org.gradle.parallel=true | Enable by default (gradle.properties) |
| --no-parallel | Force sequential for this build |
In CI
Set --max-workers to the runner vCPU count; the default can over-subscribe small runners and cause OOM. Parallel builds expose hidden inter-project dependencies, so a build that only fails under --parallel usually has an undeclared task input/output.
Common errors in CI
"Gradle daemon disappeared unexpectedly" or worker exit value 137 under --parallel is over-subscription OOM; lower --max-workers or raise heap. "Cannot have two tasks ... write to the same file" or non-deterministic failures point to projects sharing an output directory, which parallel execution races on; declare proper inputs/outputs.