What is Maximum Heap Size: -Xmx?

Usage:

-XmxNNN where NNN is a number indicating the amount of memory, including an optional character indicating the unit. For example -Xmx8g indicates a maximum heap size of 8 gigabytes.

The units can be specified as:

• k, K – kilobytes
• m, M – megabytes
• g, G – gigibytes
• t, T – terabytes

WARNING: If a unit is not specified then the number indicates an exact number of bytes, e.g. -Xms64 means just 64 bytes.

Examples:

Set the maximum heap to 1024 megabytes (1 gigabyte)

java -Xmx1024m

Set the maximum heap to 64 gigabytes:

java -Xmx64g

Description:

The -Xmx argument controls the maximum size of the Java heap. This is the maximum amount of memory that can be allocated to objects across all generations.

When the JVM needs to allocate a new object, it will usually attempt to do so using memory freed by a previous garbage collection. However if there is no free space at the current heap size then the heap will be expanded, so long as it does not exceed the maximum size.

When the heap is completely full, already at the maximum, and the Java program attempts to allocate a new object, an OutOfMemoryError is thrown. At this point the application can do very little to recover and should normally shut down.

The -Xmx argument should be set to be at least as large as the peak amount of heap used by the application. As above, this should be based on measurements of production usage. Note that setting the heap to the peak value or higher does not waste memory, as the heap only grows to the maximum size if and when the application actually needs to use that much memory.

Although the maximum heap should be set to the peak expected memory usage, it should never exceed the amount of available physical memory on the computer. This is because JVM garbage collection interacts poorly with virtual memory. The garbage collector periodically scans the entire memory of the application, so if any part of the heap has been swapped out to virtual memory then this process forces it back into physical memory, often at the expense of other running applications. However this problem may become less severe in the future as the performance of SSDs and NVRAM approaches that of volatile RAM.

Default Value:

The -Xmx parameter does not have a fixed default value. If not specified then the value is chosen at runtime appropriately by the JVM, depending on the amount of physical memory available, the CPU architecture, the JVM mode (i.e. server or client), and the JVM vendor, implementation and version.

To determine the default settings of a JVM instance, the Print Flags option can be used. It will show the maximum heap size (-Xmx):

java -XX:+PrintCommandLineFlags -version

Example output of this command on a device with 16Gb of RAM:

-XX:ConcGCThreads=2 -XX:G1ConcRefinementThreads=8 -XX:GCDrainStackTargetSize=64 -XX:InitialHeapSize=268435456 -XX:MarkStackSize=4194304 -XX:MaxHeapSize=4294967296 -XX:MinHeapSize=6815736 -XX:+PrintCommandLineFlags -XX:ReservedCodeCacheSize=251658240 -XX:+SegmentedCodeCache -XX:+UseCompressedClassPointers -XX:+UseCompressedOops -XX:+UseG1GC
openjdk version "17.0.3" 2022-04-19
OpenJDK Runtime Environment Temurin-17.0.3+7 (build 17.0.3+7)
OpenJDK 64-Bit Server VM Temurin-17.0.3+7 (build 17.0.3+7, mixed mode)

This shows the maximum heap size as 4294967296 bytes, or 4Gb.

Errors:

The value of -Xmx cannot be lower than -Xms (initial/minimum heap size). The following error results if this is tried:

Error occurred during initialization of VM
Initial heap size set to a larger value than the maximum heap size

The value of -Xmx cannot be higher than the total available physical memory in the device. The following error results when setting -Xmx512T (i.e. 512 terabytes) on a device with only 16Gb RAM:

Error occurred during initialization of VM
Could not reserve enough space for 549755813888KB object heap

Arguments Related to -Xmx:

TODO: link to -Xms

Related Posts:

• To learn about different memory regions in the Java Virtual Machine, see this video clip.
• IBM documentation regarding -Xmx.
• Azul documentation: Recommended Heap Size.
• Benefits of setting initial and maximum heap size to the same value.

NOTE:

If you have additional comments, interesting experiences or even point of disagreement with this JVM argument description, please leave a comment. Your insights will help the entire 10+ million java developer community to develop one standard source of documentation for all the JVM arguments.