# Configuration

QuPath's launcher is controlled by a configuration file generated by jpackage.
It exists somewhere within the installation (probably the *app* subdirectory) and has a name like *QuPath.cfg*.

The *.cfg* file provides a way to modify some aspects of QuPath's behavior via the `[JavaOptions]` section.
The contents may change across QuPath versions, but the following gives an example:

```bash
[JavaOptions]
java-options=-Djpackage.app-version=0.3.0
java-options=-Djava.library.path=$APPDIR
java-options=--illegal-access=permit
java-options=-XX:MaxRAMPercentage=50
```

The most relevant JavaOptions you might want to change are described below.

:::{tip}
These configuration options are also very useful when running QuPath from within an IDE.
:::

## Java parameters

### Memory-related parameters

These control the amount of memory available to Java.

Note, however, that native libraries accessed via JavaCPP (e.g. OpenCV) accesses memory differently -- and the amount of memory QuPath actually uses can therefore exceed these limits.

Because many computationally/memory intensive operations use JavaCPP (e.g. pixel classification), it is usually best to keep the memory limits here relatively conservative.

:::{glossary}
- XX:MaxRAMPercentage=50
  Set the default maximum memory for the Java virtual machine to half of the system memory.

- Xmx16G
  Set the default maximum memory for the Java virtual machine to 16 GB. May be used as an alternative to `--XX:MaxRAMPercentage`

- Xms16G
  Set the default *starting* memory for the Java virtual machine to 16 GB.<br /> Setting this to be equal to `-Xmx` may slightly improve performance, since it means QuPath does not need to increase the available memory over time to reach its maximum.
:::

## System properties

These are specified with `-Dproperty.name=value`

### General system properties

:::{glossary}
- jpackage.app-version
  Application version. This *should* correspond to the QuPath version, but unfortunately it sometimes difference because of platform-specific rules, e.g. macOS forbidding the first number to be 0.

- java.library.path
  Path in which Java will look for native libraries (e.g. OpenSlide).

  You can change this if you need to make other native libraries available to QuPath extensions, e.g. to use `$APPDIR:/path/to/somewhere/else/lib`.

  Note that on Windows the separator is `;` rather than `:`.

- java.util.concurrent.ForkJoinPool.common.parallelism
  Control the number of threads used in the common ForkJoinPool.

  This determines the default parallelism of parallel streams.
  Because streams provide an easy way parallelize some operations, and they are used in several places within QuPath, this property can be useful if memory errors are seen because of too many threads relative to the amount of available memory.
:::

### QuPath-specific properties

:::{glossary}
- qupath.prefs.name
  Specify the location for the QuPath preferences, as a node name (not a file path). This is useful if you want to have two separate QuPath instances installed with different preferences, or if you are developing a QuPath extension and don't want to load extensions from another QuPath installation.

  Example use:
  `-Dqupath.prefs.name="qupath.eclipse/0.3`
:::