Configuration Reference

This page is a searchable lookup table for BIOMERO Python client configuration and shared runtime environment variables. It covers options read by SlurmClient.from_config() as well as names registered in biomero.constants.slurm_env for integration layers to forward to BIOMERO scripts.

Resolution And Precedence

For settings mapped to slurm-config.ini, BIOMERO resolves values in this order:

1. built-in defaults

2. values from slurm-config.ini

3. environment variable overrides, when supported

For sacct history settings, relative-day settings override absolute-date settings.

Runtime-only variables have no corresponding ini key. The component identified in the table consumes them directly.

Use this page as the quick lookup companion to SLURM Configuration Guide, which explains when and why you would choose each setting.

Environment Variable Lookup Table

Supported configuration env vars

Environment variable	slurm-config.ini key	Type	Runtime effect
BIOMERO_SLURM_CONFIG_FILE	—	filesystem path	Enables authoritative-file mode; only this ini file is read instead of merging the default config paths
BIOMERO_DETACHED_WORKFLOWS	not applicable	boolean	Queues supported BIOMERO workflow scripts for an external supervisor instead of executing them inline; defaults to false and requires a deployment that provides the supervisor
BIOMERO_MAX_ACTIVE_WORKFLOWS	not applicable	integer	Maximum number of non-batched workflow runs driven concurrently by the detached worker supervisor; defaults to 4
BIOMERO_SUPERVISOR_POLL_SECONDS	not applicable	integer seconds	Interval between detached workflow queue polls; defaults to 10
BIOMERO_SUPERVISOR_STARTUP_GRACE_SECONDS	not applicable	integer seconds	Delay before the first detached workflow recovery poll, allowing the OMERO processor to register and accept sub-scripts; defaults to 60
BIOMERO_SHALLOW_ZARR	not applicable	boolean	Opts BIOMERO.scripts into canonical Zarr caching and shallow-result shallowing when the importer integration is available; defaults to false and does not disable reconstruction of existing shallow inputs
SQLALCHEMY_URL	sqlalchemy_url	database URL	Overrides the [ANALYTICS] database connection URL used for workflow tracking and analytics storage
PROCESSED_DATA_FOLDER	not applicable	subfolder name	Importer-library setting for new preprocessing outputs and canonical Zarr copies; defaults to .processed when unset. For a custom folder with BIOMERO_SHALLOW_ZARR=true, set the same value on biomeroworker as on the importer container. No worker setting is needed when shallow-Zarr is disabled.
BIOMERO_SACCT_START_TIME	sacct_start_time	string date	Absolute default start date for job history queries via sacct
BIOMERO_SACCT_START_DAYS_AGO	sacct_days_ago	integer	Rolling history window in days; overrides absolute start time when valid
BIOMERO_ENV_FILE_SUBMISSION	env_file_submission	boolean	Switches submission from direct env passing to per-job env-file submission
BIOMERO_INJECT_GPU_FLAG	inject_gpu_flag	boolean	Enables dynamic GPU flag handling in generated scripts and GPU-aware submissions
BIOMERO_GPU_PARTITION	gpu_partition	string	Default fallback GPU partition for workflow submissions when GPU mode is requested
BIOMERO_GPU_GRES	gpu_gres	string	Default fallback --gres= value appended to GPU workflow submissions; mutually exclusive with gpu_gpus
BIOMERO_GPU_GPUS	gpu_gpus	string	Default fallback --gpus= value appended to GPU workflow submissions; mutually exclusive with gpu_gres
BIOMERO_DEFAULT_PARTITION	slurm_default_partition	string	Default fallback Slurm partition for workflow and conversion jobs that do not already select one
BIOMERO_IMAGE_PULL_VIA_SBATCH	slurm_image_pull_via_sbatch	boolean	Switches workflow/converter image pulls from direct remote execution to sbatch jobs
BIOMERO_PULL_CPUS	image_pull_cpus	string	CPU request used for sbatch-based image pull/build jobs
BIOMERO_PULL_MEM	image_pull_mem	string	Memory request used for sbatch-based image pull/build jobs
BIOMERO_PULL_TIME	image_pull_time	string	Time limit for the image-pull array; overrides global sbatch_time
BIOMERO_PULL_CONCURRENCY	image_pull_concurrency	integer	Maximum simultaneously running image-pull array tasks
BIOMERO_PULL_PARTITION	image_pull_partition	string	Partition for the image-pull array; overrides global sbatch_partition
BIOMERO_APPTAINER_TMPDIR	apptainer_tmpdir	string	Tmp directory exported for Apptainer/Singularity image pull/build commands
BIOMERO_APPTAINER_CACHEDIR	apptainer_cachedir	string	Cache directory exported for Apptainer/Singularity image pull/build commands
BIOMERO_SLURM_ZIP_CMD	slurm_zip_cmd	string	Overrides the ZIP command used on the cluster; zip selects Info-ZIP and its matching unzip command, while other values use 7-Zip syntax
BIOMERO_ANALYTICS_REBUILD_START_TIME	analytics_rebuild_start_time	string date	Absolute cutoff date (YYYY-MM-DD) from which events are replayed when resetting analytics view tables; leave unset to replay all events
BIOMERO_ANALYTICS_REBUILD_DAYS_AGO	analytics_rebuild_days_ago	integer	Rolling cutoff window in days for analytics view table rebuilds; overrides the absolute date when set
GPU_PARTITION	gpu_partition	string	Legacy fallback env var for GPU partition; lower priority than BIOMERO_GPU_PARTITION
GPU_GRES	gpu_gres	string	Legacy fallback env var for GPU gres; lower priority than BIOMERO_GPU_GRES
GPU_GPUS	gpu_gpus	string	Legacy fallback env var for GPU gpus; lower priority than BIOMERO_GPU_GPUS

slurm-config.ini Lookup Table

Key [SLURM] options

Key	Type	Default	Effect
slurm_data_path	string	my-scratch/data	Base path for transferred workflow data on the cluster
slurm_images_path	string	my-scratch/singularity_images/workflows	Base path for workflow containers on the cluster
slurm_converters_path	string	my-scratch/singularity_images/converters	Base path for converter containers on the cluster
slurm_script_path	string	slurm-scripts	Base path for generated or cloned job scripts
slurm_script_repo	string or empty	empty	If set, BIOMERO clones and updates job scripts from this repository instead of generating scripts locally; use with caution, because external script repos can drift out of sync with newer BIOMERO releases and are not the recommended default
slurm_data_bind_path	string or empty	unset	Injects APPTAINER_BINDPATH into job environments
slurm_conversion_partition	string or empty	unset	Partition for data conversion jobs; injected as a real --partition flag on the conversion sbatch (and exported as CONVERSION_PARTITION). Takes precedence over slurm_default_partition for conversion jobs
slurm_default_partition	string or empty	unset	Generic fallback --partition appended to workflow and conversion jobs that do not already set a partition; per-workflow params, the GPU partition, and slurm_conversion_partition take precedence. Overridable via BIOMERO_DEFAULT_PARTITION
sacct_start_time	string date or empty	2023-01-01	Absolute start date used when listing historical jobs
sacct_days_ago	integer or empty	unset	Relative history window; takes precedence over sacct_start_time
env_file_submission	boolean	false	Uses env-file based submission instead of direct environment propagation
inject_gpu_flag	boolean	false	Enables dynamic GPU submission support in generated scripts
gpu_partition	string or empty	unset	Shared fallback partition appended for GPU workflow runs when needed
gpu_gres	string or empty	unset	Shared fallback --gres= value appended for GPU workflow runs; mutually exclusive with gpu_gpus
gpu_gpus	string or empty	unset	Shared fallback --gpus= value appended for GPU workflow runs; mutually exclusive with gpu_gres
sbatch_<key>	string or empty	unset	Any [SLURM] key starting with sbatch_ adds --<key>=<value> to workflow, conversion, and scheduled image-pull submissions; more-specific workflow, conversion, or image_pull_* values take precedence
slurm_image_pull_via_sbatch	boolean	false	Uses sbatch jobs instead of direct remote execution for workflow/converter image pulls
image_pull_cpus	string or empty	unset	CPU request for sbatch-based image pull/build jobs; blank inherits sbatch_cpus-per-task, then the scheduler default
image_pull_mem	string or empty	unset	Memory request for sbatch-based image pull/build jobs; blank inherits sbatch_mem, then the scheduler default
image_pull_time	string or empty	unset	Time limit for the image-pull array; blank inherits sbatch_time
image_pull_concurrency	integer	1	Maximum simultaneously running array tasks; configure 2-4 to bound filesystem pressure
image_pull_partition	string or empty	unset	Partition for image initialization; blank inherits sbatch_partition
apptainer_tmpdir	string or empty	unset	Fallback build-temp parent when SLURM_TMPDIR is unavailable
apptainer_cachedir	string or empty	unset	Fallback task-cache parent when SLURM_TMPDIR is unavailable
slurm_zip_cmd	string or empty	$(command -v 7z || command -v 7za)	Command used for ZIP creation and extraction on the HPC. Set to zip to use the Info-ZIP zip/unzip pair.
analytics_rebuild_start_time	string date or empty	unset	Absolute cutoff date (YYYY-MM-DD) from which events are replayed when resetting analytics view tables; leave unset to replay all events. Configured under [ANALYTICS].
analytics_rebuild_days_ago	integer or empty	unset	Rolling cutoff window in days for analytics view table rebuilds; overrides the absolute date when set. Configured under [ANALYTICS].
<name>_use_gpu	boolean	false	Per-workflow GPU default in [WORKFLOWS] (or [MODELS] for legacy configs); e.g. cellpose_use_gpu=true marks a workflow as GPU-enabled so BIOMERO activates GPU handling without requiring an explicit use_gpu argument at submission time
<name>_repo	string URL	—	GitHub URL for a workflow in [WORKFLOWS] (or [MODELS]). Accepts either a repository tree URL (…/tree/vX.Y.Z) or a direct URL to a specific descriptor file (…/tree/vX.Y.Z/descriptor.json, …/tree/vX.Y.Z/config.yaml). With a plain tree URL, BIOMERO auto-discovers the descriptor (tries descriptor.json → descriptor.yaml → config.yaml in order). With a direct URL, only that exact file is fetched — useful when a repository contains both a BIAflows descriptor.json and a bilayers config.yaml and you want to choose which interface to expose.

Behaviour Notes

Parsing scope

The boolean and integer fallback rules below apply to options resolved by SlurmClient.from_config(). Runtime-only variables define their own parsing contract. BIOMERO_SHALLOW_ZARR is enabled only by the case-insensitive literal value true; an absent or different value leaves the opt-in feature disabled. BIOMERO_DETACHED_WORKFLOWS accepts the case-insensitive values 1, true, yes and on; it is disabled when absent or set to any other value.

Detached worker supervisor

New in version 2.9.0: BIOMERO_DETACHED_WORKFLOWS is an opt-in feature flag. It is disabled when absent or false. Existing deployments retain inline execution until an administrator enables the feature and provides a compatible worker supervisor.

The four detached variable names are centralized in biomero.constants.slurm_env and form one deployment contract. The workflow scripts and worker both read BIOMERO_DETACHED_WORKFLOWS. The three supervisor settings are consumed only by deployments that provide a detached workflow supervisor, such as the NL-BIOMERO biomeroworker container; they do not configure SlurmClient and do not need entries in slurm-config.ini.

After the launcher has recorded the workflow request, detached execution no longer depends on the browser tab or the OMERO session that submitted it. The Slurm run, monitoring, and result import may therefore outlive ordinary OMERO server and web-session timeouts. Do not increase those timeouts merely to cover the complete workflow duration. They must still be long enough for initial validation and hand-off, and for each OMERO-side transfer or import subprocess. Without a compatible supervisor, keep detached mode disabled: the established inline path still depends on the calling script and session until it finishes.

Supervisor values are converted to integers when the worker process starts, so non-integer values prevent that process from loading. Use a positive value for BIOMERO_MAX_ACTIVE_WORKFLOWS and non-negative second values for both timing settings. A startup grace of 0 skips the initial delay.

PROCESSED_DATA_FOLDER is read by the importer library at module import time, not from slurm-config.ini. Its value is used as supplied (for example, .import); an explicitly empty value does not select the default. NL-BIOMERO’s processor forwards names registered in biomero.constants.slurm_env to OMERO script subprocesses. The variable must still be present in the worker container’s environment, and its BIOMERO and importer libraries must support this setting. Existing canonical locations are read from stored metadata; changing the variable neither relocates existing data nor rewrites those references.

Boolean parsing

Supported truthy values are:

• true

• 1

• yes

• y

• on

Supported falsy values are:

• false

• 0

• no

• n

• off

Invalid boolean env var values fall back to the already resolved ini or default value.

Integer parsing

Invalid integer env var values also fall back to the already resolved ini or default value. This matters especially for BIOMERO_SACCT_START_DAYS_AGO.

Empty-string handling

Some optional string settings treat an empty value as unset rather than as a literal empty string. This is relevant for values such as slurm_data_bind_path, slurm_conversion_partition, slurm_default_partition, gpu_partition, gpu_gres, gpu_gpus, and the optional sacct window settings.

GPU precedence

For workflow submissions, GPU-related settings are applied in this order:

1. per-workflow sbatch parameters from [WORKFLOWS] (or [MODELS]) such as cellpose_job_partition, cellpose_job_gres, and cellpose_job_gpus

2. global sbatch defaults from sbatch_<key> entries in [SLURM]

3. shared runtime GPU defaults: gpu_partition and either gpu_gres (--gres=) or gpu_gpus (--gpus=); these two are mutually exclusive — set one or the other, never both

4. no BIOMERO-added GPU resource arguments

Shared GPU defaults (level 3) are considered when GPU mode is active. GPU mode is activated by one of two code paths:

• Dynamic path (inject_gpu_flag=true): use_gpu is resolved at submission time — explicit use_gpu argument wins, otherwise falls back to <name>_use_gpu from [WORKFLOWS]/[MODELS]. GPU_FLAG env var is set (--nv or empty) at submission time so the script can toggle the container runtime flag.

• Static path (inject_gpu_flag=false): --nv is baked into the generated script at script-generation time; only <name>_use_gpu=true in [WORKFLOWS]/[MODELS] triggers GPU sbatch resource param injection, and it cannot be overridden at submission time. No GPU_FLAG env var is set.

See SLURM Configuration Guide for a full explanation of the interaction between these settings.

Search Hints

If you are looking for a specific name, try searching the docs for any of these exact identifiers:

• BIOMERO_SACCT_START_TIME

• SQLALCHEMY_URL

• BIOMERO_DETACHED_WORKFLOWS

• BIOMERO_MAX_ACTIVE_WORKFLOWS

• BIOMERO_SUPERVISOR_POLL_SECONDS

• BIOMERO_SUPERVISOR_STARTUP_GRACE_SECONDS

• BIOMERO_SHALLOW_ZARR

• PROCESSED_DATA_FOLDER

• BIOMERO_SACCT_START_DAYS_AGO

• BIOMERO_ENV_FILE_SUBMISSION

• BIOMERO_INJECT_GPU_FLAG

• BIOMERO_GPU_PARTITION

• BIOMERO_GPU_GRES

• BIOMERO_GPU_GPUS

• BIOMERO_DEFAULT_PARTITION

• BIOMERO_IMAGE_PULL_VIA_SBATCH

• BIOMERO_PULL_CPUS

• BIOMERO_PULL_MEM

• BIOMERO_APPTAINER_TMPDIR

• BIOMERO_APPTAINER_CACHEDIR

• BIOMERO_SLURM_ZIP_CMD

• BIOMERO_ANALYTICS_REBUILD_START_TIME

• BIOMERO_ANALYTICS_REBUILD_DAYS_AGO

• GPU_PARTITION

• GPU_GRES

• GPU_GPUS

Optional result shallower

The administrator-only CPU helper runs before result ZIP creation. All options are in [SLURM]; environment values override ini values. Shallow Zarr remains opt-in; when enabled, remote shallowing is the default. Set remote_shallow_zarr=false or BIOMERO_REMOTE_SHALLOW_ZARR=false to use local importer shallowing instead, for example to avoid extra Slurm costs. The helper requests no GPU; workers set CPUs per task. Shallowing and recovery share conversion’s resource merging: the helper partition overrides slurm_default_partition, which overrides global sbatch_partition. Otherwise Slurm chooses its default. Global sbatch_* options (including account, reservation, QoS and constraint) are inherited, except GPU resources, multi-task/node allocation and flags owned by the helper (array, command, export and log paths). Optional helper memory and time limits override their global counterparts; otherwise global values apply. Image pulls use the normal image-pull resource configuration.

The import script owns session keepalive and supplies a heartbeat callback to the shared SlurmJob monitor for shallowing and recovery. Callback failures propagate unchanged. This applies to inline and detached workflows alike. An existing job ID is adopted without resubmission; unavailable status pauses retrieval rather than triggering recovery. The helper task is completed only after its output report has been validated.

Only SLURM_Init_environment acquires the shallower image. Verify setup with SLURM_check_setup before running workflows. Runtime shallowing validates the installed image and raises a setup error if it is missing or invalid; it never downloads an image or silently falls back because setup is incomplete.

Shallowing and recovery have distinct submission identities. Recorded job IDs remain authoritative when resuming older tasks; an unresolved pre-upgrade recovery intent may require administrator reconciliation, rather than automatic resubmission.

Canonical input manifests are published atomically and verified on resume, never overwritten. Missing manifests after submission or changed inputs stop retrieval. New tasks record an input fingerprint and the helper SIF path; existing tasks retain their recorded image and tool version for recovery and receipt validation even when deployment defaults change. Keep the original SIF available until those tasks finish. Resource settings remain configurable.

Result shallower configuration

Ini option	Default	Environment variable
remote_shallow_zarr	true (shallow Zarr must be enabled separately)	BIOMERO_REMOTE_SHALLOW_ZARR
remote_shallower_image	cellularimagingcf/biomero-shallower:latest; prefer an ini pin	BIOMERO_REMOTE_SHALLOWER_IMAGE
remote_shallower_version	Unset; read the installed image’s OCI version label	BIOMERO_REMOTE_SHALLOWER_VERSION
remote_shallower_workers	1	BIOMERO_REMOTE_SHALLOWER_WORKERS
remote_shallower_partition	Unset (inherit generic partition)	BIOMERO_REMOTE_SHALLOWER_PARTITION
remote_shallower_mem	Unset (inherit global memory)	BIOMERO_REMOTE_SHALLOWER_MEM
remote_shallower_time	Unset (inherit global time limit)	BIOMERO_REMOTE_SHALLOWER_TIME

Prefer a versioned tag or immutable digest and matching importer/schema/shallower versions. Importer enablement, existing shallow capability, and workflow tracking are required. Safe failures fall back to full transfer and local import; unresolved recovery preserves results and pauses retrieval. These options are administrator settings, not scientific workflow parameters. A compatible OMERO.biomero admin interface exposes them when shallow storage is enabled; environment overrides still take precedence over values saved to the ini file.

Core falls back to our helper’s :latest tag. Prefer an image pin in [SLURM]; refer to resources/slurm-config.ini for the maintained release selection. When remote_shallower_version is unset, core reads the installed SIF’s OCI version label and records it before submitting a new task. An explicit value overrides discovery and must match the Python package version written into receipts, including any normalized prerelease suffix. Existing tasks retain their recorded version for recovery.

An explicit :latest image tag is accepted, as with configured converters, but is not a reproducible release pin. Initialization reuses an already valid SIF; it does not refresh that file merely because the registry tag moved. Keep any explicit expected tool version consistent with the installed image. Initialization acquires the configured or default image. Missing version labels require an explicit tool-version setting; receipt validation is not disabled. Importer trust configuration must still match the selected image and actual tool version.

For recovery behavior and component responsibilities, see Execution, storage and recovery.