skip to content

org.gradle.jvmargs Heap & Metaspace

4 roadmaps5 questions

Sizing the daemon JVM with org.gradle.jvmargs — heap, metaspace, and a heap dump on out-of-memory. Asked because a long-lived daemon is precisely where metaspace leaks and OOM failures surface.

on this pageshow

explore

questions

5

What is org.gradle.jvmargs and where do you set it to control the Gradle daemon's heap?

level: juniorimportance: must knowfreq 62%

answer

  1. JVM args for the daemon JVM
  2. lives in gradle.properties
  3. project-root vs ~/.gradle precedence
  4. not forked test/JavaExec JVMs
  5. default 512m/1g

basics

~10 s

org.gradle.jvmargs is a Gradle property that passes JVM flags (like -Xmx) to the build daemon's JVM. You set it in gradle.properties, usually in the project root or the user's ~/.gradle directory.

solid answer

~40 s

`org.gradle.jvmargs` is a Gradle property whose value is the list of JVM startup arguments applied to the **Gradle daemon** — the long-lived JVM that actually runs your build. It is where you size the daemon's heap (`-Xmx`), metaspace (`-XX:MaxMetaspaceSize`), and add diagnostics like `-XX:+HeapDumpOnOutOfMemoryError`. You set it in a `gradle.properties` file: the project-root file (committed, applies to everyone building this project) or `~/.gradle/gradle.properties` (per-machine, not committed). Project-level usually wins for build-specific needs. It does **not** affect tasks that fork their own JVMs (e.g. `JavaExec`, `Test`) — those have their own `jvmArgs`/`maxHeapSize`. Gradle's default for the daemon is modest (historically 512m, 1g in newer versions), so memory-heavy builds frequently override it.

code

toml · 2 lines
toml
# gradle.properties
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

go deeper

for a junior

Know it passes -Xmx and friends to the build's JVM and lives in gradle.properties.

for a middle

Explain project-root vs user-home precedence and that forked JVMs are separate.

for a senior

Discuss committing a sane baseline for CI/devs vs per-machine tuning, and diagnostics flags.

for a principal

Set org-wide conventions: a committed baseline in project gradle.properties plus guidance on user-home overrides, encoding, and heap-dump destinations across many repos.

## What the property is The Gradle build runs inside a JVM called the **daemon** — a background process Gradle keeps alive between invocations so it doesn't pay JVM-startup and class-loading costs every time. `org.gradle.jvmargs` is the Gradle property that supplies the **startup arguments for that daemon JVM**. Its value is a space-separated list of standard JVM flags. The most common are: - `-Xmx<size>` — maximum heap size for the daemon. - `-Xms<size>` — initial heap size. - `-XX:MaxMetaspaceSize=<size>` — cap on metaspace (where class metadata lives). - `-XX:+HeapDumpOnOutOfMemoryError` — write a heap dump when an OOM occurs, so you can diagnose it. - `-Dfile.encoding=UTF-8` — and other system properties the build needs. ## Where you set it It lives in a **`gradle.properties`** file. Gradle reads these in order of increasing precedence: 1. `GRADLE_USER_HOME/gradle.properties` (default `~/.gradle/gradle.properties`) — per-machine, **not** committed; good for developer-machine sizing. 2. Project-root `gradle.properties` — **committed**, applies to everyone building the project; good for the project's baseline requirement. 3. Command line / environment overrides. For a property that needs to apply to CI and every developer, the project-root file is the canonical home. For machine-specific tuning, the user-home file. ## What it does NOT control `org.gradle.jvmargs` sizes the **build's own JVM**, not the JVMs your build forks. The `Test` task, `JavaExec`, `JavaCompile` with `options.fork`, etc. start **separate** JVMs that have their own `jvmArgs` / `maxHeapSize` / `minHeapSize`. A common confusion is bumping `org.gradle.jvmargs` to fix an OOM that is actually happening in a forked test worker — that needs the `Test` task's own heap settings. ```properties # gradle.properties org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 ``` ## Default and why people change it Gradle ships a conservative default (historically 512 MB, raised to 1 GB in recent versions). Large multi-module builds, annotation-processor-heavy builds (Kotlin, KAPT, Dagger), and builds that load many plugins routinely exceed it, so overriding `org.gradle.jvmargs` is one of the first build-environment changes teams make.

  • If you put org.gradle.jvmargs in both ~/.gradle/gradle.properties and the project-root file, which wins?
    The project-root file has higher precedence than the user-home file for that property, so the project-root value wins. (Command-line/system-property overrides beat both.)
  • Your test task throws OutOfMemoryError but bumping org.gradle.jvmargs didn't help. Why?
    The Test task forks its own worker JVM(s); it doesn't run in the daemon's heap. You must raise the Test task's maxHeapSize (and minHeapSize/jvmArgs), not org.gradle.jvmargs.

saying these in an interview costs you the question

  • Claiming org.gradle.jvmargs sets heap for forked test/JavaExec JVMs — it only sizes the daemon itself.
  • Saying it must go in build.gradle — it is a properties-file setting, not a build-script DSL line.

context

resolving links…

open as a page

A large multi-module build fails with 'java.lang.OutOfMemoryError: Java heap space' during configuration/compilation. How do you diagnose and fix it via the daemon JVM args?

level: middleimportance: must knowfreq 55%

basics

~10 s

Confirm the OOM is in the daemon (not a forked test worker), then raise the daemon heap in gradle.properties via org.gradle.jvmargs=-Xmx (e.g. -Xmx3g) and add -XX:+HeapDumpOnOutOfMemoryError to capture a dump if it recurs.

open as a page

How do you choose org.gradle.jvmargs heap/metaspace values across local machines and CI agents, and what trade-offs guide the numbers?

level: seniorimportance: should knowfreq 34%

basics

~20 s

Commit a sane baseline in the project gradle.properties that fits the smallest target (CI agent), and let powerful dev machines bump it via ~/.gradle/gradle.properties. Size so daemon heap plus forked workers fit RAM, leaving OS headroom.

open as a page

What is metaspace, why do long-lived Gradle daemons hit 'OutOfMemoryError: Metaspace', and how does MaxMetaspaceSize fit into the fix?

level: seniorimportance: should knowfreq 38%

basics

~20 s

Metaspace is native memory holding class metadata. A reused daemon loads classes across many builds; leaked classloaders accumulate metadata until 'OutOfMemoryError: Metaspace'. Set -XX:MaxMetaspaceSize to a sane cap (and fail fast with a dump) rather than leaving it unbounded.

open as a page

Besides -Xmx, what other JVM flags are commonly worth putting in org.gradle.jvmargs, and what is Gradle's default if you set nothing?

level: middleimportance: nice to knowfreq 26%

basics

~10 s

If unset, Gradle uses a modest default heap (historically 512m, 1g in recent versions). Beyond -Xmx, common additions are -XX:MaxMetaspaceSize, -XX:+HeapDumpOnOutOfMemoryError, -Dfile.encoding=UTF-8, and sometimes -XX:+UseParallelGC or other GC/locale/encoding flags.

open as a page