Paquo uses dynaconf for configuration management.

Paquos internal settings are configurable via a .paquo.toml file or via environment variables. If anything remains unclear after reading this section, please open an issue in the github repository!

The .paquo.toml file

To configure you paquo installation you can place a .paquo.toml file in a spot where paquo can find it. To list all possible locations (note: it’s very many) run:

user@computer:~$ python -m paquo config --search-tree

This will output all search locations. These partially depend on where you run paquo from, which allows you to override certain settings for a project you’re working on by having a custom .paquo.toml file in a project related location.

To get a default template for the .paquo.toml run:

user@computer:~$ python -m paquo config --list --default

This outputs the contents of the default paquo config toml:

 1# paquo's default configuration
 2# =============================
 3# format: TOML
 5# if set will skip search and try to use qupath from there:
 6qupath_dir = ""
 8# default search paths for qupath
 9qupath_search_dirs = [
10  "/opt",  # linux
11  "/Applications",  # macos
12  "c:/Program Files",  # win
13  "/usr/local",  # linux
14  "~/Applications",  # macos
15  "~/AppData/Local",  # win
16  "~",
18# used to match qupath_dirs during search
19qupath_search_dir_regex = "(?i)qupath.*"
20# search for the qupath conda package?
21qupath_search_conda = true
22# prefer the qupath conda package?
23qupath_prefer_conda = true
25# options passed to the JVM.
26# - one option per string item
27java_opts = [
28  "-XX:MaxRAMPercentage=50",
31# paquo options
32safe_truncate = true
34# allows to use a different jvm_path for running qupath
35jvm_path_override = ""
37# internal settings
38# -----------------
39# allows building the docs without qupath
40mock_backend = false
41# only show paquo errors on cli
42cli_force_log_level_error = true
43# on windows warn about microsoft store python
44warn_microsoft_store_python = true


If you want to store this in the directory ./config run

user@computer:~$ python -m paquo config -l -o `./config`

This will write a .paquo.toml file in the specified directory 🎉 (The directory must already exist)

Environment variables

All paquo settings can also be overridden by environment variables. Just prefix the particular setting with PAQUO_ (single underscore!) and set the environment variable to what you want it to be.


if set will skip search and try to use qupath from this folder


defaults to all default installation locations for QuPath this can be set to the folders that will be searched for QuPath installations.


used to regex match qupath_dirs during search


should the conda installed QuPath be considered?


should the conda installed QuPath be preferred over another locally installed QuPath

PAQUO_JAVA_OPTS = ["-XX:MaxRAMPercentage=50",]

a list of JVM options passed to the java virtual machine


an internal setting which allows building the docs without having qupath installed


only show paquo errors on cli


windows only, warn if paquo is run via a microsoft store python

Verifying the config

The easiest way to verify if your current configuration is correct is to run the command below, which will output something like the following to the console, and represents your current config:

user@computer:~$ python -m paquo config --list
# current paquo configuration
# ===========================
# format: TOML
qupath_dir = ""
qupath_search_dirs = [ "/usr/local",]
qupath_search_dir_regex = "(?i)qupath.*"
qupath_search_conda = true
qupath_prefer_conda = true
java_opts = [ "-XX:MaxRAMPercentage=50",]
mock_backend = false


Or if you want to go directly via dynaconf you can run

user@computer:~$ dynaconf -i paquo.settings list


Paquo uses Python’s logging for console debug output. There’s two logger namespaces for paquo: “paquo” and “qupath”. “paquo” logs paquo internal things and the java loggers are reroutet through the “qupath” logger.