Environment variables

CrateDB can be configured with some environment variables.

There are many different ways to set environment variables, depending on how CrateDB is being deployed.

Here is a trivial example:

sh$ export CRATE_HOME=/tmp/crate
sh$ ./bin/crate

Here, we set CRATE_HOME to /tmp/crate, export it so that sub-processes of the shell have access, and then start CrateDB.

CrateDB supports two kinds of environment variables:

  • Application variables
  • Java Virtual Machine (JVM) variables

We use “application” here to distinguish between CrateDB running as a Java application and the JVM itself, which runs CrateDB.

Table of contents

Application variables

CRATE_HOME: directory path

The home directory of the CrateDB installation.

This directory is used as the root for the configuration directory, data directory, log directory, and so on.

If you have installed CrateDB from a package, this variable should be set for you.

If you are installing manually, in most cases, this should be set to the directory from which you would normally execute bin/crate, i.e. the root directory of the expanded tarball.

JVM variables


CRATE_JAVA_OPTS: Java options

The Java options to use when running CrateDB.

For example, you could change the stack size like this:


See also

For more information about Java options, consult the documentation for Microsoft Windows or Unix-like operating systems.


The Java heap size, i.e. the amount of memory that can be used.

You can set the heap size to four gigabytes like this:


Use g for gigabytes or m for megabytes.

See also

Appropriate memory configuration is important for optimal performance.

CRATE_HEAP_DUMP_PATH: file or directory path (default: varies)

The directory to be used for heap dumps in the case of a crash.

If a directory path is configured, new heap dumps will be written to that directory every time CrateDB crashes.

If a file path is configured (i.e. the last node of the path is non-existent or exists and is a file) CrateDB will overwrite that file with a heap dump every time it crashes.

Default values are as follows:


Make sure there is enough disk space available for heap dumps.

Garbage collection


CrateDB uses the G1 garbage collector by default.

Before CrateDB 4.1 it defaulted to use the Concurrent Mark Sweep garbage collector. If you’d like to continue using CMS, you can switch setting the following CRATE_JAVA_OPTS:

export CRATE_JAVA_OPTS="-XX:-UseG1GC -XX:+UseCMSInitiatingOccupancyOnly -XX:+UseConcMarkSweepGC"


CrateDB logs JVM garbage collection times using the built-in garbage collection logging of the JVM.

See also

The logging configuration documentation has the complete list of garbage collection logging environment variables.


How helpful was this page?