Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

Heap size is an essential parameter of Java applications. It directly affects how much memory we can use and indirectly impacts the applications’ performance. For example, the usage of compressed pointers, the number and duration of garbage collection cycles, etc.

In this tutorial, we’ll learn how to use the –XX:MaxRAM flag to provide more tuning opportunities for the heap size calculation. This is especially important while running an application inside a container or on different hosts.

2. Heap Size Calculations

Flags for configuring a heap can work together and, also, can override each other. Understanding their relationships is important to get more insights into their purpose.

2.1. Using -Xmx

The primary ways to control the heap size are -Xmx and -Xms flags, which control the maximum and initial size, respectively. It’s a powerful tool but doesn’t consider available space on a machine or container. Let’s say we’re running an application on various hosts where the available RAM spans from 4 GB to 64 GB.

Without -Xmx, JVM automatically allocates around 25% of available RAM for the application heap. However, in general, the initial heap size allocated by JVM depends on various parameters: system architecture, version of JVM, platform, etc.

This behavior might be undesirable in some cases. Depending on the available RAM, it might allocate dramatically different heaps. Let’s check how much JVM allocates by default on the machine with 24 GB of RAM:

$ java -XX:+PrintFlagsFinal -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize' 
   size_t InitialHeapSize   = 402653184    {product} {ergonomic}
   size_t MaxHeapSize       = 6442450944   {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

JVM allocated roughly 6 GB or 25%, which might be too much for our application. Setting the max heap to a specific value might also create issues. If we’re using -Xmx4g, it might fail for hosts with less than available memory, and also, we won’t get additional memory we can have:

$ java -XX:+PrintFlagsFinal -Xmx4g -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 402653184    {product} {ergonomic}
   size_t MaxHeapSize       = 4294967296   {product} {command line}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

In some cases, this problem can be solved by calculating -Xmx on the fly with scripts. However, it bypasses the JVM heuristic that might be more precise about the application needs.

2.2. Using -XX:MaxRAM

The flag -XX:MaxRAM aims to resolve the problem described above. First, it prevents JVM from over-allocating memory on the systems with lots of RAM. We can think about this flag as “run the app, but pretend that you have at most X amount of RAM.”

Additionally, -XX:MaxRAM allows JVM to use a standard heuristic for the heap size. Let’s review the previous example, but using -XX:MaxRAM:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=6g -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 100663296    {product} {ergonomic}
   size_t MaxHeapSize       = 1610612736   {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

JVM calculates the maximum heap size in this case but assumes we have only 6 GB of RAM. Note that we should not use -Xmx with -XX:MaxRAM. Because -Xmx is more specific, it would override -XX:MaxRAM:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=6g -Xmx6g -version |\ 
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 100663296    {product} {ergonomic}
   size_t MaxHeapSize       = 6442450944   {product} {command line}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

This flag can improve resource utilization and heap allocation. However, we still don’t have control over how much of the RAM should be allocated to the heap.

2.3. Using -XX:MaxRAMPercentage and -XX:MinRAMPercentage

Now we’re in control and can tell JVM how much RAM it should consider. Let’s define our strategies for allocating the heap. The -XX:MaxRAM flag works well with -XX:MaxRAMPercentage and -XX:MinRAMPercentage. They provide even more flexibility, especially in containerized environments. Let’s try to use it with -XX:MaxRAM and set the heap as 50% of available RAM:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=6g -XX:MaxRAMPercentage=50 -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 100663296    {product} {ergonomic}
   size_t MaxHeapSize       = 3221225472   {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

There’s a common confusion about the -XX:MinRAMPercentage. It doesn’t behave as -Xms. Although, it would be reasonable to assume that it sets the minimum heap size. Let’s check the following setup:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=16g -XX:MaxRAMPercentage=10 -XX:MinRAMPercentage=50 -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 268435456    {product} {ergonomic}
   size_t MaxHeapSize       = 1719664640   {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

We set both -XX:MaxRAMPercentage and -XX:MinRAMPercentage, but it’s clear that only -XX:MaxRAMPercentage is working. We allocated 10% of 16 GB RAM to the heap. However, if we reduce the available RAM to 200 MB, we’ll get a different behavior:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=200m -XX:MaxRAMPercentage=10 -XX:MinRAMPercentage=50 -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize' 
   size_t InitialHeapSize   = 8388608      {product} {ergonomic}
   size_t MaxHeapSize       = 109051904    {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

In this case, the heap size is controlled by -XX:MinRAMPercentage. This flag kicks in when the available RAM drops to less than 200 MB. Now, we can bump the heap to 75%:

$ java -XX:+PrintFlagsFinal -XX:MaxRAM=200m -XX:MaxRAMPercentage=10 -XX:MinRAMPercentage=75 -version |\
grep -e '\bMaxHeapSize\|\bMinHeapSize\|\bInitialHeapSize'
   size_t InitialHeapSize   = 8388608      {product} {ergonomic}
   size_t MaxHeapSize       = 134217728    {product} {ergonomic}
   size_t MinHeapSize       = 8388608      {product} {ergonomic}

If we proceeded to apply -XX:MaxRAMPercentage for such tiny heaps, we would get 20 MB of heap, which might not be enough for our purposes. That’s why we have different flags for small and large heaps. The -XX:MaxRAM flag works nicely with both of them and gives us more control.

3. Conclusion

Controlling heap size is crucial for Java applications. Allocating more memory isn’t necessarily good; at the same time, allocating not enough memory is bad.

Using -Xmx, -XX:MaxRAM, -XX:MaxRAMPercentage, and -XX:MinRAMPercentage can help us tune our application better and improve performance.

Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

7 Comments
Oldest
Newest