# Configure JVM Options

You can configure the properties and JVM options for your YouTrack instance. The YouTrack properties include various launch configuration settings. The JVM options let you manage behavioral, garbage collection, performance, and debugging options for your server.

The most common use case for editing the default JVM options for your YouTrack Server installation is when you perform an operation that places a heavy load on the server. This can include importing content from an external source or running bulk updates on a large number of issues. If you initiate a process that fails due to server timeouts or memory limits, you can temporarily increase the Java heap or Metaspace memory until the operation is complete.

* YouTrack provides default values for JVM options that affect the performance and memory allocation for your YouTrack installation. For a complete list, see [Default JVM Options](#mandatory-jvm-options).

* Other parameters affect the availability of specific features and other application behavior. For a complete list of YouTrack-specific configuration parameters, see [Configuration Parameters](youtrack-java-start-parameters.html).

JVM options that differ from the default configuration are stored in an internal file named `youtrack.jvmoptions`. Every time you start the YouTrack service, YouTrack reads this file and applies the parameters that are stored in this configuration to the YouTrack instance.

There are two methods that you can use to update these parameters:

| Method | Description |
| --- | --- |
| [Update the parameter on a persistent basis](#set-jvm-options). | To change the value of a parameter on a persistent basis, you can either:       * Set the value programmatically using the `configure` command.    * Update the JVM option manually in the `youtrack.jvmoptions` file.   |
| [Update the parameter temporarily](#set-ad-hoc-parameter). | You can pass the JVM option on a temporary basis as an ad hoc start parameter. The value for the parameter is set for the current run only. The `youtrack.jvmoptions` file is not updated, so when you restart your YouTrack instance without the start parameter, the parameter resets to the value that is stored in the configuration.     Use this option to test changes to your environment before you apply them on a persistent basis.   |

## Update JVM Options on a Persistent Basis

When you want to update a JVM option on a persistent basis, update the `youtrack.jvmoptions` file. You can update the file programmatically, or manually change the settings in the file.

When you set a YouTrack property or JVM option, the property is applied on every server restart.

### Set JVM Options Using Command Line Arguments

You can set properties and JVM options for your server with the `configure` command. You can use this method for any type of YouTrack installation.

When you set JVM options from the command line, consider the following guidelines:

* Always execute the `configure` command on behalf of the OS user that runs the YouTrack service. This command creates configuration files and folders. The YouTrack service user should have sufficient permissions to access these files and folders.

* To set the parameter for a JVM option, enter the `configure` command with the prefix `-J`. The `-J` prefix signifies that a JVM option is declared after it. You must add the `-J` prefix to each JVM option that you want to configure.

* The `D` prefix signifies that the name value pair that follow it are used as a system property within the JVM.

* To define an option passed to YouTrack by the JVM on start, use `-` before the parameter name: `youtrack configure -J-<jvm.property>[=<value>]` For example: ```CONSOLE youtrack configure -J-Dorg.eclipse.jetty.server.Request.maxFormKeys=10000 youtrack configure -J-Xmx1024m -J-XX:+HeapDumpOnOutOfMemoryError ```

* To remove a JVM option, use `+` before the parameter name: `youtrack configure -J+<jvm.property>[=<value>]` The constructions `+option=<value>`, `+XX:<option>=<value>` and `+D<property>=<value>` remove the corresponding option only if it has exactly the same value. For example: ```CONSOLE youtrack configure -J+Dorg.eclipse.jetty.server.Request.maxFormKeys=10000 ``` The constructions `+option`, `+XX:<option>` and `+D<property>` remove the corresponding option regardless of the value. For example: ```CONSOLE youtrack configure -J+ea ```

Procedure: To set a JVM option from the command line in a Docker container:

1. Stop YouTrack:

```CONSOLE
docker exec <containerId> stop
```

2. Run the following command:

> **Note:**
> To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment.

Linux (Bash):

```CONSOLE
docker run --rm -it \
-v <path to conf directory>:/opt/youtrack/conf \
jetbrains/youtrack:<version> \
configure -J-<jvm.property>=<value>
```

Windows (PowerShell):

```CONSOLE
docker run --rm --it `
-v <path to conf directory>:/opt/youtrack/conf `
jetbrains/youtrack:<version> `
configure -J-<jvm.property>=<value>
```

* Replace `<jvm.property>` with the name of the property that you want to update.

* Replace `<value>` with the value that you want to set.

For example:

```CONSOLE
configure -J-Dstatistics-upload=true
```

3. Start YouTrack:

```CONSOLE
docker start <containerId>
```

### Update JVM Options Manually

You can configure JVM options manually by editing the `youtrack.jvmoptions` file. This file is created automatically when you modify the default configuration. The location of the file depends on the distribution type of your YouTrack installation.

> **Note: Changing Database Location**
> You cannot change the database location manually. This parameter is rewritten on server start. To change the database location, see [Change Database Location](changing-database-location.html).

If you have not changed the JVM options for your server, the directory contains a sample configuration file. The sample configuration file uses the `.dist` extension and contains a list of default JVM options. If the file you want to edit does not exist:

* Copy the youtrack.jvmoptions.dist file and save it as youtrack.jvmoptions or

* Create a youtrack.jvmoptions file in this directory and paste the contents of the sample configuration file into it.

You can then edit the contents of the file to configure the JVM options as described in the following procedure.

Procedure: To update JVM options manually in a Docker container:

1. Stop YouTrack:

```CONSOLE
docker exec <containerId> stop
```

2. Open the youtrack.jvmoptions file.

For a Docker image, the file is located in the `conf` directory on the host machine that is mapped to the `/opt/youtrack/conf` directory inside the container.

3. Start YouTrack:

```CONSOLE
docker start <containerId>
```

## Update JVM Options Temporarily

When you want to modify a JVM option on a temporary basis, you can use an ad hoc parameter in the service start command. This method bypasses the `youtrack.jvmoptions` file and runs YouTrack with the specified parameters. Subsequent starts that do not specify the ad hoc parameter use the JVM options that are stored in the configuration file.

Procedure: To pass a JVM option as an ad hoc parameter in a Docker image:

1. Use the following command to stop the YouTrack service:

```CONSOLE
docker exec <containerId> stop
```

2. > **Note:**
> To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment.

Run the `configure-next-start` command:

Linux (Bash):

```CONSOLE
docker run -it --rm \
-v <path to conf directory>:/opt/youtrack/conf \
jetbrains/youtrack:<version> \
configure-next-start \
<ad hoc JVM options>
```

Windows (PowerShell):

```CONSOLE
docker run -it --rm `
-v <path to conf directory>:/opt/youtrack/conf `
jetbrains/youtrack:<version> `
configure-next-start `
<ad hoc JVM options>
```

For the `<ad hoc JVM options>`, specify the list of JVM options that should be applied on the next start of YouTrack service. Specify the ad hoc JVM options in the following format:

```
--J<JVM option>
```

`--J` is the ad hoc prefix followed by the option. Do not add any spaces between the prefix and the option. The symbol that precedes the option determines how it is applied.

* Add an option with the `-` symbol.

* Ignore an option with the `+` symbol. If you specify a value, the corresponding option is only ignored if it has exactly the same value.

For example:

Linux (Bash):

```CONSOLE
docker run -it --rm \
-v <path to conf directory>:/opt/youtrack/conf
jetbrains/youtrack:<version> \
configure-next-start \
--J-XX:+HeapDumpOnOutOfMemoryError \
--J-Xmx1024m
```

Windows (PowerShell):

```CONSOLE
docker run -it --rm `
-v <path to conf directory>:/opt/youtrack/conf `
jetbrains/youtrack:<version> `
configure-next-start `
--J-XX:+HeapDumpOnOutOfMemoryError `
--J-Xmx1024m
```

3. Restart the YouTrack service:

```CONSOLE
docker start <containerId>
```

* The YouTrack service starts using the specified settings.

* The `youtrack.jvmoptions` file is not modified.

To run YouTrack with the previous settings, restart the service without passing any custom parameters.

## Check JVM Options

After changing JVM options for your YouTrack installation you might want to check that your changes are applied. To do so, you can use a `list jvm-options` command. It produces a list of JVM properties that will be applied to the YouTrack instance on the next start. Please note that the output of the command lists only persistent JVM options. Any options that are provided ad hoc in the command to run YouTrack will override the value of the same persistent option.

## Default JVM Options

To run YouTrack, the following JVM options are set by default for all installations:

| Setting | JVM Option | Value |
| --- | --- | --- |
| Maximum Metaspace memory | `-XX:MaxMetaspaceSize` | `350m` |
| Maximum Java heap size | `-Xmx` | `1024m` or `1g` |

> **Note: Smart Memory Management**
> Whenever the application is restarted, it checks the current database size, excluding BLOBs (binary large objects, like attachments and large blocks of text).
>
>
>
> If the database exceeds the maximum Java heap size that is currently allocated to run the application, it automatically increases the allocation by 250 MB unless this number would be greater than 80% of the total memory available to the application.
>
>
>
> The application will continue to increase the maximum heap size until it covers the size of the existing database or reaches the 80% limit.

The following JVM options help you manage and improve the performance of your YouTrack installation:

| Setting | JVM Option | Value |
| --- | --- | --- |
| Minimum Metaspace memory | `-XX:MetaspaceSize` | `350m` |