starfish commands can all be configured in a unified way.

If the STARFISH_CONFIG environment variable is set, then it will be loaded, either (1) as a JSON file if the value starts with @ or (2) as a JSON string for all other values. For example:

export STARFISH_CONFIG=@~/.my.starfish
export STARFISH_CONFIG='{"verbose": false}'

Otherwise, ~/.starfish/config will be loaded if it exists and is a valid JSON file. If neither is true, then only the default values will apply.

Additionally, the individual properties from the configuration JSON can be set by environment variable. These values take precedence if also set in the configuration file. For example:

    "validation": {
        "strict": true

can also be specified as:


Other valid values for “true” are: “TRUE”, “True”, “yes”, “y”, “1”, “on”, and “enabled”.

Default values

To not require any mandatory configuration, the following values will be assumed if no configuration is available.

    "slicedimage": {
        "caching": {
            "debug": false,
            "directory": "~/.starfish/cache",
            "size_limit": 5e9
    "validation": {
        "strict": false
    "verbose": true

Main environment variables


The primary configuration variable is STARFISH_CONFIG. By default, it is equivalent to ~/.starfish/config which need not exist.


Strict validation will run the equivalent of starfish validate on every experiment that is loaded. Execution will halt with an exception. The initial loading of an experiment will also take longer since files must be downloaded for validation. If caching is enabled, the overall impact should not be significant.


Whether or not various commands should should print internal status messages. By default, true.

Backend environment variables

Starfish currently uses the slicedimage library as a backend for storing large image sets. Configuration values starting with SLICEDIMAGE_ (or optionally, STARFISH_SLICEDIMAGE_) will be passed to the backend without modification.


Maximum size of the cache directory. By default, size_limit is 5GB. Setting size_limit to 0 disables caching.


Directory where the cache will be stored. By default, the directory ~/.starfish/cache.


Whether or not to print which files are being cached. By default, false.