Elasticsearch Understanding and Optimizing Elasticsearch -Xmx Setting

By Opster Team

Updated: Jul 23, 2023

| 2 min read


The Elasticsearch –Xms and Xmx settings are critical configuration parameters that can significantly impact the performance and stability of your Elasticsearch cluster. These settings control the initial and maximum heap size allocated to the Java Virtual Machine (JVM) running Elasticsearch. 

The JVM heap size is the amount of memory that the JVM can use for dynamic memory allocation. This memory is used for storing objects created by your application and Elasticsearch itself. If the heap size is too small, the JVM may run out of memory, causing Elasticsearch to crash or perform poorly. Conversely, if the heap size is too large, it can cause excessive garbage collection pauses, which can also degrade performance. If you want to learn about Elasticsearch cluster blocks read-only, check out this guide.

How to Set the Elasticsearch Heap Settings

The -Xms and -Xmx settings can be specified as a command-line option when starting Elasticsearch. For example, to set the maximum heap size to 2 gigabytes, you would start Elasticsearch with the following command:

ES_JAVA_OPTS="-Xms2g -Xmx2g" ./bin/elasticsearch

This command sets the initial and maximum heap size to 2 gigabytes. The ‘g’ suffix indicates gigabytes. You can also use ‘m’ for megabytes or ‘k’ for kilobytes.

Alternatively, it is also possible to define a custom JVM options file with the extension `.options` (to be located in the Elasticsearch configuration folder called `config/jvm.options.d`) with the following content:


Optimizing the Elasticsearch Heap Settings

The optimal heap setting depends on the specific requirements and constraints of your application. However, there are some general guidelines that you can follow.

  1. Set the heap to 50% of your total physical RAM: Elasticsearch uses off-heap memory for certain operations,. By limiting the heap size to 50% of your total RAM, you ensure that there is enough memory left for these off-heap operations.
  1. Do not exceed ~30GB: The JVM can use compressed object pointers (OOPs) for heap sizes up to around ~30GB. Using compressed OOPs reduces the memory overhead of each object reference, allowing the JVM to store more data in the same amount of memory. If you set -Xmx to more than ~30GB, the JVM will not be able to use compressed OOPs, which can significantly increase the memory overhead and reduce performance.
  1. Set -Xms equal to -Xmx: The -Xms setting controls the initial heap size allocated by the JVM. By setting -Xms equal to -Xmx, you prevent the JVM from having to resize the heap at runtime, which can cause pauses and degrade performance.

Monitoring and Adjusting the Heap Setting

You should regularly monitor the memory usage of your Elasticsearch cluster to ensure that the heap settings are appropriate. If you see frequent garbage collection pauses or out-of-memory errors, you may need to increase the heap setting. Conversely, if you see that the heap usage is consistently low, you may be able to reduce the heap setting to free up memory for other uses.

You can monitor memory usage using the Elasticsearch _nodes/stats API. This API provides detailed statistics about the memory usage and garbage collection activity of your cluster.


In conclusion, the Elasticsearch heap settings are critical configuration parameters that can significantly impact the performance and stability of your Elasticsearch cluster. By understanding how they work and how to optimize them, you can ensure that your Elasticsearch cluster runs smoothly and efficiently.

How helpful was this guide?

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?