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.

For a complete list of YouTrack-specific configuration parameters, see Configuration Parameters.

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

Method	Description
Update the parameter on a persistent basis.	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.	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.

Method

Description

Update the parameter on a persistent basis.

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.

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

You can set JVM options in a command-line interface or manually edit the configuration file.

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

Set JVM Options from the Command Line

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 that is passed to YouTrack by the JVM on start, use - before the parameter name: youtrack configure -J-<jvm.property>[=<value>]
For example:
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:
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:
youtrack configure -J+ea

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

Stop YouTrack:
docker exec <containerId> stop
Execute the following command:
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:
configure -J-Dstatistics-upload=true
Start YouTrack:
docker start <containerId>

To set a JVM option from the command line in a JAR installation:

Open a command-line interface and enter the following command to stop the YouTrack service:
java -jar youtrack-<version>.jar stop
Enter the configure command. For example:
<youtrack_home>bin/youtrack.sh configure -J-Dstatistics-upload=true
Use the following command to restart the YouTrack service:
java -jar youtrack-<version>.jar

To set a JVM option from the command line in an MSI installation:

Use the Services Microsoft Management Console (MMC) to stop the Windows service that runs YouTrack (Control Panel > Administrative Tools > Services).
Open the Command Prompt window as an administrator.
Enter the configure command. For example:
<youtrack_home>bin\youtrack.bat configure -J-Dstatistics-upload=true
Switch back to the Services Microsoft Management Console (MMC) and restart the YouTrack Windows service.

To set a JVM option from the command line in a ZIP installation:

Open a command-line interface and enter the following command to stop the YouTrack service:
youtrack.sh stop
Enter the configure command. For example:
<youtrack_home>bin/youtrack.sh configure -J-Dstatistics-upload=true
Use the following command to restart the YouTrack service:
youtrack.sh restart

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.

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.

To update JVM options manually in a Docker container:

Stop YouTrack:
docker exec <containerId> stop
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.
Start YouTrack:
docker start <containerId>

To update JVM options manually for a JAR installation:

Open a command-line interface and enter the following command to stop the YouTrack service:
java -jar youtrack-<version>.jar stop
Open the youtrack.jvmoptions file.
For a JAR distribution, the file is located in the ${user.home}/teamsysdata/conf directory.
Edit the JVM options directly in the file. To set the value for a pre-defined JVM option, remove the special characters that mark the corresponding line as a comment and change the property to the desired value.
Save and close the file.
Use the following command to restart the YouTrack service:
java -jar youtrack-<version>.jar

To update JVM options manually for an MSI installation:

Use the Services Microsoft Management Console (MMC) to stop the Windows service that runs YouTrack (Control Panel > Administrative Tools > Services).
Open the youtrack.jvmoptions file.
For an MSI distribution the file is located in the %programdata%\JetBrains\YouTrack\conf directory.
You can locate the path to the conf folder in the <YouTrack installation directory>\internal\conf\installation.xml file. The path is written to the property default-appdata-root. For example:
<default-appdata-root>C:\ProgramData\JetBrains\YouTrack</default-appdata-root>
Edit the JVM options directly in the file. To set the value for a pre-defined JVM option, remove the special characters that mark the corresponding line as a comment and change the property to the desired value.
Save and close the file.
Switch back to the Services Microsoft Management Console (MMC) and restart the YouTrack Windows service.

To update JVM options manually for a ZIP installation:

Open a command-line interface and enter the following command to stop the YouTrack service:
youtrack.sh stop
Open the youtrack.jvmoptions file.
For a ZIP distribution, the file is located in the <YouTrack installation directory>/conf directory.
Edit the JVM options directly in the file. To set the value for a pre-defined JVM option, remove the special characters that mark the corresponding line as a comment and change the property to the desired value.
Save and close the file.
Use the following command to restart the YouTrack service:
youtrack.sh restart

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.

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

Use the following command to stop the YouTrack service:
docker exec <containerId> stop
Run the configure-next-start command:
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:
docker run -it --rm \ -v <path to conf directory>:/opt/youtrack/conf jetbrains/youtrack:<version> \ configure-next-start \ --J-XX:+HeapDumpOnOutOfMemoryError \ --J-Xmx1024m
Restart the YouTrack service:
docker start <containerId>
- The YouTrack service starts using the specified settings.
- The youtrack.jvmoptions file is not modified.

When you run YouTrack as a stand-alone Java process, you can also set the JVM options in the command that you use to run YouTrack. For example:

java -jar youtrack-xx.jar --J-Xmx1024m <port>

In this case, the JVM option is applied ad hoc. These options are reset the next time you stop and restart the service. To set a JVM option on a persistent basis, always use the configure command as described in the previous section.

To pass a JVM option as an ad hoc parameter in an MSI installation:

Use the Services Microsoft Management Console (MMC) to stop the Windows service that runs YouTrack (Control Panel > Administrative Tools > Services).
In a command-line interface, change the directory to <youtrack_home>\bin.
For an MSI installation, the <youtrack_home> directory is the location where the MSI distribution was installed. The default installation directory is C:\YouTrack
Enter the youtrack.bat start command, followed by the settings that you want to pass to the YouTrack database on start.
- Use the --J prefix to pass the settings as ad hoc parameters.
- Follow the prefix with a JVM 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:
youtrack.sh start --J-XX:+HeapDumpOnOutOfMemoryError --J-Xmx1024m
- The YouTrack service starts using the specified settings.
- The youtrack.jvmoptions file is not modified.

To pass a JVM option as an ad hoc parameter in a ZIP installation:

In a command-line interface, enter the following command to stop the YouTrack service:
youtrack.sh stop
Change the directory to <youtrack_home>/bin.
For a ZIP installation, the <youtrack_home> directory is the location where the ZIP distribution was unpacked during installation.
Enter the youtrack.sh start command, followed by the settings that you want to pass to the YouTrack database on start.
- Use the --J prefix to pass the settings as ad hoc parameters.
- Follow the prefix with a JVM 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:
youtrack.sh start --J-XX:+HeapDumpOnOutOfMemoryError --J-Xmx1024m
- 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`

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`

Last modified: 21 April 2023