Docs
You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elasticsearch Reference [master] » Set up Elasticsearch » Configuring Elasticsearch » Setting JVM options
« Configuring Elasticsearch Secure settings »

Setting JVM optionsedit

You should rarely need to change Java Virtual Machine (JVM) options. If you do, the most likely change is setting the heap size. The remainder of this document explains in detail how to set JVM options. You can set options either with jvm.options files or with the ES_JAVA_OPTS environment variable.

The preferred method of setting or overriding JVM options is via JVM options files. When installing from the tar or zip distributions, the root jvm.options configuration file is config/jvm.options and custom JVM options files can be added to config/jvm.options.d/. When installing from the Debian or RPM packages, the root jvm.options configuration file is ``/etc/elasticsearch/jvm.options` and custom JVM options files can be added to /etc/elasticsearch/jvm.options.d/. When using the Docker distribution of Elasticsearch you can bind mount custom JVM options files into /usr/share/elasticsearch/config/jvm.options.d/. You should never need to modify the root jvm.options file instead preferring to use custom JVM options files. The processing ordering of custom JVM options is lexicographic.

JVM options files must have the suffix .options and contain a line-delimited list of JVM arguments following a special syntax:

  • lines consisting of whitespace only are ignored

  • lines beginning with # are treated as comments and are ignored

    # this is a comment

  • lines beginning with a - are treated as a JVM option that applies independent of the version of the JVM

    -Xmx2g

  • lines beginning with a number followed by a : followed by a - are treated as a JVM option that applies only if the version of the JVM matches the number

    8:-Xmx2g

  • lines beginning with a number followed by a - followed by a : are treated as a JVM option that applies only if the version of the JVM is greater than or equal to the number

    8-:-Xmx2g

  • lines beginning with a number followed by a - followed by a number followed by a : are treated as a JVM option that applies only if the version of the JVM falls in the range of the two numbers

    8-9:-Xmx2g
  • all other lines are rejected

An alternative mechanism for setting Java Virtual Machine options is via the ES_JAVA_OPTS environment variable. For instance:

export ES_JAVA_OPTS="$ES_JAVA_OPTS -Djava.io.tmpdir=/path/to/temp/dir"
./bin/elasticsearch

When using the RPM or Debian packages, ES_JAVA_OPTS can be specified in the system configuration file.

The JVM has a built-in mechanism for observing the JAVA_TOOL_OPTIONS environment variable. We intentionally ignore this environment variable in our packaging scripts. The primary reason for this is that on some OS (e.g., Ubuntu) there are agents installed by default via this environment variable that we do not want interfering with Elasticsearch.

Additionally, some other Java programs support the JAVA_OPTS environment variable. This is not a mechanism built into the JVM but instead a convention in the ecosystem. However, we do not support this environment variable, instead supporting setting JVM options via the jvm.options file or the environment variable ES_JAVA_OPTS as above.

« Configuring Elasticsearch Secure settings »