Mastering JVM Heap Settings in Docker: Best Parameters Across JDK Versions

When configuring JVM on physical or virtual machines, the JVM defaults to using 1/4 of host memory for heap, but you can set -Xmx / -Xms. In container environments, memory limits are set by Cgroups, and older JVMs have limited Cgroup support. This article explores optimal JVM parameters.

JDK 1.8.0_121 (pre‑1.8.0_131)

Running a container with the openjdk:8u121 image without specifying parameters makes the JVM ignore Cgroup limits and use 1/4 of host memory as max heap.

# free -m
total        used        free      shared  buff/cache   available
Mem:          7196        2557         299         117        4338        4219
Swap:            0           0           0

# docker run -m 512Mi openjdk:8u121 java -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 1.56G
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

Specifying -Xms and -Xmx makes the JVM recognize the limits.

# docker run -m 512Mi openjdk:8u121 java -Xms512m -Xmx512m -XshowSettings:vm -version
VM settings:
    Min. Heap Size: 512.00M
    Max. Heap Size: 512.00M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

JDK 1.8.0_131

With the openjdk:8u131 image, the JVM still defaults to 1/4 of host memory unless parameters are set.

# docker run -m 512Mi openjdk:8u131 java -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 1.56G
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

Using -Xms and -Xmx works as expected.

# docker run -m 512Mi openjdk:8u131 java -Xms512m -Xmx512m -XshowSettings:vm -version
VM settings:
    Min. Heap Size: 512.00M
    Max. Heap Size: 512.00M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

From JDK 1.8.0_131 onward, two new flags are available:

-XX:+UnlockExperimentalVMOptions

-XX:+UseCGroupMemoryLimitForHeap

These enable the JVM to detect Cgroup memory limits, but the max heap is still limited to 1/4 of the Cgroup memory.

To adjust the fraction, -XX:MaxRAMFraction and -XX:MinRAMFraction can be used (integer values only). The following table shows valid values:

Example with -XX:MaxRAMFraction=2 yields a max heap of ~50% of the Cgroup limit.

# docker run -m 512Mi openjdk:8u131 java -XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -XX:MaxRAMFraction=2 -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 228.00M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

JDK 1.8.0_191

With openjdk:8u191-alpine, the JVM automatically detects Cgroup limits and sets the max heap to 1/4 of the limit.

# docker run -m 512Mi openjdk:8u191-alpine java -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 123.75M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

Specifying -Xms and -Xmx works as expected.

# docker run -m 512Mi openjdk:8u191-alpine java -Xms512m -Xmx512m -XshowSettings:vm -version
VM settings:
    Min. Heap Size: 512.00M
    Max. Heap Size: 512.00M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

From JDK 1.8.0_191, -XX:MaxRAMFraction and -XX:MinRAMFraction are deprecated. Use -XX:MaxRAMPercentage and -XX:MinRAMPercentage (double values with a decimal point) to control the heap proportion.

# docker run -m 512Mi openjdk:8u191-alpine java -XX:MaxRAMPercentage=50.0 -XX:MinRAMPercentage=50.0 -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 247.50M
    Ergonomics Machine Class: server
    Using VM: OpenJDK 64‑Bit Server VM

Xms

and Xmx work for all JDK versions but cannot dynamically sense Cgroup limits; they have highest priority. -XX:+UnlockExperimentalVMOptions and -XX:+UseCGroupMemoryLimitForHeap enable dynamic detection from JDK 1.8.0_131, but limit heap to 1/4 of Cgroup memory. -XX:MaxRAMFraction and -XX:MinRAMFraction allow adjusting the fraction from JDK 1.8.0_131, but values are limited and deprecated after JDK 1.8.0_191. -XX:MaxRAMPercentage and -XX:MinRAMPercentage (available from JDK 1.8.0_191) let you set any percentage.

These recommendations apply to containers using Cgroups v1. For Cgroups v2, you need JDK 1.8.0_372, 11.0.16 or newer to detect memory limits.

Use a JDK version that can sense Cgroup limits (≥ 1.8.0_191 for v1, ≥ 1.8.0_372 or 11.0.16 for v2).

Allocate container memory limit higher than the heap (add 20‑30% for off‑heap usage) and adjust based on monitoring.

If a single Java process runs in the container, set -Xms and -Xmx to the same value to avoid extra GC overhead.

Enable -XX:+HeapDumpOnOutOfMemoryError and -XX:HeapDumpPath to persist dumps on OOM.