This article attempts to clarify the difference between InitialRAMPercentage, MinRAMPercentage, MaxRAMPercentage JVM arguments. These arguments have been introduced since Java 8 update 191. They are used to configure your Java application’s heap size when you are running it in the Physical server or in the container. In this article, let’s review their differences.

InitialRAMPercentage
‘-XX:InitialRAMPercentage’ is used to compute the initial heap size of your java application. Say suppose you are configuring -XX:InitialRAMPercentage=25 and overall physical memory (or container memory) is 1GB then your java application’s heap size will be ~250MB (i.e., 25% of 1GB).

‘-XX:InitialRAMPercentage’ will be used to derive initial heap size only if ‘-Xms’ JVM argument isn’t passed. If the ‘-Xms’ JVM argument is passed, the ‘-XX:InitialRAMPercentage’ will be ignored by the JVM.

MaxRAMPercentage, MinRAMPercentage
Both ‘-XX:MaxRAMPercentage’ and ‘-XX:MinRAMPercentage’ are used to determine the maximum Java heap size. JDK development team could have given a better name than ‘-XX:MinRAMPercentage’. This name makes us think, ‘-XX:MinRAMPercentage’ argument is used to configure minimum heap size. But it’s not true.

‘-XX:MinRAMPercentage’ JVM argument will be used to compute Java heap size only if your overall available memory’s size in the physical server (or in the container) is less than 250MB (approximately). Say suppose you are configuring -XX:MinRAMPercentage=50 and overall physical memory (or container) memory is 100MB, then your java application’s max heap size will be set to 50MB (i.e., 50% of 100MB).

‘-XX:MaxRAMPercentage’ JVM argument will be used to compute Java heap size only if your overall available memory’s size in the physical server (or in container) is more than 250MB(approximately). Say suppose you are configuring -XX:MaxRAMPercentage=75 and overall physical server (or container) memory is 1GB, then your java application’s max heap size will be set to 750MB (i.e., 75% of 1GB).

To prove this theory, consider the below two examples.

Example 1: Small memory size

Let’s configure the container’s memory size to be 100MB, MaxRAMPercentage to be 25, and MinRAMPercentage to be 50. Since the container’s memory size is 100MB (which is less than the 250MB limit), JVM uses ‘MinRAMPercentage’ to derive the heap’s size. You can notice JVM reporting max heap size for this configuration to be 48.38M (i.e., 50% of the 100MB). You can see ‘MaxRAMPercentage’ JVM argument to be ignored.

# docker run -m 100MB openjdk:10 java -XX:MaxRAMPercentage=25 -XX:MinRAMPercentage=50 -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 48.38M
    Using VM: OpenJDK 64-Bit Server VM

Example 2: Large memory size

Let’s configure the container’s memory size to be 1GB, MaxRAMPercentage to be 25, and MinRAMPercentage to be 50. Since the container’s memory size is 1GB (which is greater than the 250MB limit), JVM uses ‘MaxRAMPercentage’ to derive the heap’s size. You can notice JVM reporting max heap size for this configuration to be 247.50M (i.e. 25% of the 1GB). You can see the ‘MinRAMPercentage’ JVM argument to be ignored.

# docker run -m 1GB openjdk:10 java -XX:MaxRAMPercentage=25 -XX:MinRAMPercentage=50 -XshowSettings:vm -version
VM settings:
    Max. Heap Size (Estimated): 247.50M
    Using VM: OpenJDK 64-Bit Server VM

‘-XX:MaxRAMPercentage’ and ‘-XX:MinRAMPercentage’ will be used to derive maximum heap size only if ‘-Xmx’ JVM argument isn’t passed. If the ‘-Xmx’ JVM argument is passed, the JVM will ignore these two arguments.

In the below example you can see ‘-XX:MaxRAMPercentage=25’, ‘-XX:MinRAMPercentage=25’ and ‘-Xmx512m’ are configured. You can see the max heap size is set to 512M, it’s indicating value specified in the ‘-Xmx’ is taking effect.

# docker run -m 1GB openjdk:10 java -XX:MaxRAMPercentage=25 -XX:MinRAMPercentage=25 -Xmx512m -XshowSettings:vm -version
VM settings:
    Max. Heap Size: 512.00M
    Using VM: OpenJDK 64-Bit Server VM

Best Practice: When you are starting to use ‘’, ‘’, ‘’ JVM arguments it has potential to impact your garbage collection, performance characteristics of your application. You can use free tools like GCeasy, IBM GC & Memory Visualizer, HP jmeter to study this behavior.

Conclusion
Thus, in a nutshell:

a. To set the initial heap size for your application use ‘-XX:InitialRAMPercentage’

b. ‘-XX:InitialRAMPercentage’ will not take effect to determine the initial heap size if ‘-Xms’ is configured.

c. Both ‘-XX:MinRAMPercentage’ and ‘-XX:MaxRAMPercentage’ are used to set the application’s max heap size.

d. ‘-XX:MinRAMPercentage’ and ‘-XX:MaxRAMPercentage’ will not take effect to determine max heap size if ‘-Xmx’ is configured.

e. If your overall physical server (or container) memory size is more than 250MB, then you don’t have to configure ‘-XX:MinRAMPercentage’, it’s sufficient if you just configure ‘-XX:MaxRAMPercentage’. Most enterprise grade Java applications will be running with more than 250MB (unless you are building IoT or network device applications in Java).