MaxRAMPercentage and Container Awareness for the JVM
How the JVM reads container limits: MaxRAMPercentage, InitialRAMPercentage, MinRAMPercentage, availableProcessors and how to confirm what the JVM sees.

A container with a 1 GiB memory limit runs a Java service, and the heap never grows past 256 MiB while the other 700 MiB sits idle. Or the opposite: someone sets -Xmx1g on a 1 GiB container, and the kernel kills the process an hour later with exit code 137, because the heap is not the only memory a JVM uses. Both problems come from the same place, how the JVM decides its own size inside a cgroup. This post shows what the JVM sees, what each percentage flag does, how to pick a number, and how to verify it from inside a running container. The examples assume JDK 25 and a Linux container runtime with cgroups v2.
What the JVM sees
Since JDK 10 (and backported to 8u191) the JVM is container aware. It reads the memory and CPU limits from the cgroup filesystem instead of looking at the host. You can prove it with a few lines:
package dev.javahacks.jvm;
public class WhatISee {
public static void main(String[] args) {
Runtime rt = Runtime.getRuntime();
System.out.println("processors = " + rt.availableProcessors());
System.out.println("max heap MiB = " + rt.maxMemory() / (1024 * 1024));
}
}Run it in a container capped at 2 CPUs and 1 GiB:
docker run --rm --cpus=2 --memory=1g -v "$PWD":/work -w /work eclipse-temurin:25-jdk \
java -XX:+UseG1GC dev/javahacks/jvm/WhatISee.javaprocessors = 2
max heap MiB = 256The JVM saw 2 processors and sized the default maximum heap at 25 percent of the 1024 MiB limit, which is 256 MiB. The default of 25 percent is conservative on purpose: the heap is only a part of the memory a JVM process needs, as explained in JVM memory areas.
The three percentage flags
| Flag | Default | What it sets |
|---|---|---|
-XX:MaxRAMPercentage | 25 | Maximum heap as a share of available memory |
-XX:InitialRAMPercentage | 1.5625 | Heap size at startup |
-XX:MinRAMPercentage | 50 | Maximum heap for tiny memory (under about 256 MiB) |
The odd one is MinRAMPercentage. Despite the name, it is not a minimum heap. It is the maximum-heap percentage used instead of MaxRAMPercentage when the available memory is very small, because 25 percent of 128 MiB is too little to run anything. Most services never reach that branch.
Set the maximum to 70 and look at the result:
docker run --rm --memory=1g -v "$PWD":/work -w /work eclipse-temurin:25-jdk \
java -XX:MaxRAMPercentage=70 dev/javahacks/jvm/WhatISee.javaprocessors = 4
max heap MiB = 7161024 times 0.70 is 716.8, and the JVM reports 716. The processor count is the host's, here 4, because this run passed no --cpus limit.
Why percentages instead of -Xmx
An absolute -Xmx512m is correct for exactly one container size. When the same image runs with a 512 MiB limit in a test namespace and 4 GiB in production, the fixed number is wrong in one of them: too big and the process is killed, or too small and the memory is wasted. A percentage scales with the limit, so one image and one flag work everywhere.
Precedence matters. If -Xmx is present, it wins and the percentage is ignored. A stray -Xmx baked into a base image or in JAVA_TOOL_OPTIONS silently disables your MaxRAMPercentage. Find out which options reached the JVM, as described in [setting JVM options in Docker with JAVA_TOOL_OPTIONS](/library/java-tool-options-docker-set-jvm).
How much to allow
The heap is not the process. A JVM also holds metaspace, thread stacks, code cache, garbage collector structures, direct byte buffers and native libraries. A rough budget for a service with 200 threads:
| Area | Typical size | Notes |
|---|---|---|
| Heap | what you set | Max RAM percentage times the limit |
| Metaspace | 80 to 200 MiB | Grows with classes loaded |
| Thread stacks | 200 threads x 1 MiB = 200 MiB | Virtual threads cost far less |
| Code cache | 48 to 240 MiB | Bounded by ReservedCodeCacheSize |
| GC and misc | 5 to 10 percent of heap | Larger for G1 with a huge heap |
On a 1 GiB container, 75 percent heap is 768 MiB, which leaves 256 MiB for everything else. With 200 platform threads and a large metaspace that is not enough, and the container is killed by the kernel when the total crosses the limit. The symptom and the evidence trail are in diagnosing a container killed by OOMKilled.
A workable starting point:
- Limit under 512 MiB: 50 percent, since the fixed overhead is a large share.
- Limit 1 to 4 GiB: 60 to 70 percent.
- Limit above 8 GiB: 75 to 80 percent, because the overhead no longer scales with the heap.
These are starting points, not laws. The way to settle it is to run the service under realistic load and read the resident memory against the limit. A detailed method, with measured headroom, is in Java heap size in a container with real numbers.
Where to set it
Choose the place that survives the next person's edit.
FROM eclipse-temurin:25-jre
COPY target/app.jar /app/app.jar
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70 -XX:InitialRAMPercentage=50"
ENTRYPOINT ["java", "-jar", "/app/app.jar"]In Kubernetes, override it per environment without rebuilding the image:
containers:
- name: shop
image: registry.example.test/shop:1.4.2
resources:
limits:
memory: 1Gi
cpu: "2"
env:
- name: JAVA_TOOL_OPTIONS
value: "-XX:MaxRAMPercentage=70"Setting InitialRAMPercentage close to the maximum, as in the Dockerfile, makes the heap start large and avoids repeated resizing during warmup. The price is that the process commits that memory early, so it fits a service that will use it anyway and not a sidecar.
Checking container support
Do not trust a flag you have not read back. Ask the running JVM:
java -XX:+PrintFlagsFinal -XX:MaxRAMPercentage=70 -version | grep -E 'MaxRAMPercentage|MaxHeapSize|UseContainerSupport' double MaxRAMPercentage = 70.000000 {product} {command line}
uintx MaxHeapSize = 751828992 {product} {ergonomic}
bool UseContainerSupport = true {product} {default}UseContainerSupport is on by default. If a legacy image or a wrapper script turns it off with -XX:-UseContainerSupport, the JVM reads the host's memory and sizes the heap for a machine that you do not have. Inside a running container you can also read the raw limit the JVM reads:
cat /sys/fs/cgroup/memory.max1073741824A value of max means no limit, and the JVM falls back to host memory. The flags and their defaults are documented in the java command reference, including the container support section.
CPU consequences
The CPU limit has an equal effect that people miss. availableProcessors() is derived from --cpus (rounded up), and a great many things size themselves from it: the common fork-join pool, the number of GC threads, the default sizing of parallel streams and many library thread pools. A service allowed 0.5 CPU sees 1 processor. Tune pools deliberately, as in sizing thread pools for CPU and I/O, rather than trusting the derived number. If the derived value is wrong for your workload, -XX:ActiveProcessorCount=4 overrides it.
Where this does not apply
If the limit is an unbounded max, these flags scale with the host instead, which is rarely what you want on a shared node, so set a limit. A JVM running outside a container has the whole machine as its limit, and a plain -Xmx is clearer there. And a workload dominated by off-heap memory, such as a service using large direct buffers or memory-mapped files, needs a lower heap percentage than the table suggests, because the heap is the smaller part of its footprint.


