Java -Xms parameter: Initial Heap Size

Usage:

-XmsNNN where NNN is a number indicating the amount of memory, including an optional character indicating the unit.

Example:

-Xms256m

Indicates an initial heap size of 256 megabytes. You can specify the values in:

• 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.

What is -Xms

The -Xms argument controls the initial and minimum size of the Java heap. This is the amount of memory that is immediately reserved for the heap by the JVM at start-up, and the size below which the heap will not be allowed to drop. Note that this is not the minimum total size of the JVM process in memory because of the other types of memory regions (stack, JVM internals, etc.) as explained in this video.

Most applications do not need to specify -Xms and will work fine without it.

However, if you know that your application will need at least a certain amount of heap immediately after starting, it may be beneficial to reserve at least that much at start time. If this is not done then the JVM will have to incrementally request more memory from the operating system each time the heap needs to grow, which can be slower in aggregate than requesting all of the memory at once.

For this reason it is generally recommended to set -Xms to the application’s stable heap usage level, based on historical measurements of the application in production usage.

Default Value

The -Xms parameter does not have a fixed default value. If not specified then the value is chosen at runtime appropriately by the JVM. It depends on the amount of physical memory available, the JVM mode (i.e. server vs 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 initial heap size (-Xms):

java -XX:+PrintCommandLineFlags -version

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

-XX:InitialHeapSize=263845056 -XX:MaxHeapSize=4221520896 -XX:+PrintCommandLineFlags -XX:+UseCompressedClassPointers -XX:+UseCompressedOops -XX:-UseLargePagesIndividualAllocation -XX:+UseParallelGC

java version "1.8.0_321"

Java(TM) SE Runtime Environment (build 1.8.0_321-b07)

Java HotSpot(TM) 64-Bit Server VM (build 25.321-b07, mixed mode)

This shows the initial heap size as 263845056 bytes, or about 252Mb.

Errors

The value of -Xms cannot be higher than -Xmx (maximum 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 -Xms cannot be higher than the total available physical memory in the device. The following error results when setting -Xms512T (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 -Xms

• TODO: link to -Xmx

Related Posts

1. To learn about different memory regions in the Java Virtual Machine, see this video clip.
2. IBM documentation regarding -Xms.
3. Azul documentation: Recommended Heap Size.
4. 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.