Environment Variables (v5.0+)

(Advanced) Specify additional environment variables in the configuration files to augment CryoSPARC's low-level behaviour.

Environment variables

To set or change one of these environment settings, add a new line to one the config.sh files with the following format (substitute VARIABLE and VALUE as indicated in the next sections):

export VARIABLE="VALUE"

Or set the value based on a different environment variable provided by the system:

export VARIABLE="${OTHER_VARIABLE}"

Which config.sh file you use depends on which variable you need to change. The variables available for each file are described below.

cryosparc_master/config.sh

Note: Restart CryoSPARC with cryosparcm restart after changing this file.

Variable	Description	Default Value
CRYOSPARC_CLIENT_TIMEOUT	How many seconds to wait for network requests between CryoSPARC master/master processes before timing out with an error	300
CRYOSPARC_CLUSTER_JOB_MONITOR_INTERVAL	The amount of time to wait (in seconds) in between status updates for cluster jobs.	10
CRYOSPARC_CLUSTER_JOB_MONITOR_MAX_RETRIES	The maximum amount of retries for cluster job status updates.	1000000
CRYOSPARC_DB_CONNECTION_TIMEOUT_MS	The amount of time to wait (in milliseconds) for the database to respond when starting it.	20000
CRYOSPARC_DB_ENABLE_AUTH	Enables authentication for MongoDB database operations	true
CRYOSPARC_FORCE_HOSTNAME	In master/worker or cluster modes, cryosparcm commands always run on the machine where cryosparc_master was initially installed. Set this to true to allow running on any machine	false
CRYOSPARC_FORCE_USER	cryosparcm commands must be run by the same UNIX user account that owns the cryosparc_master installation. Set this to true to allow running cryosparcm from any user account	false
CRYOSPARC_IGNORE_HIDDEN_FILES	When checking that job directory is empty before running a job, set to true to ignore any filenames that being with .. Use this if your file system or OS automatically creates hidden files	false
CRYOSPARC_IO_URING	Set to false to force-disable io_uring for fast disk read operations during jobs. May be required for some older operating systems or systems with an incorrect io_uring implementation.	true
CRYOSPARC_LICENSE_SERVER_ADDR	Override CryoSPARC license server address. Use for systems that require access through a proxy.	https://get.cryosparc.com
CRYOSPARC_MONGO_CACHE_GB	How much RAM to allocate for MongoDB database query cache, in GB	4
CRYOSPARC_MOTION_CORRECTION_CPUS_PER_GPU	How many CPU cores to allocate for each GPU used in Patch, Full-frame and Local Motion Correction jobs	6
CRYOSPARC_MOTION_CORRECTION_RAM_MB_PER_GPU	How much RAM (in MB) to allocate for each GPU used in Patch, Full-frame and Local Motion Correction jobs	15000
CRYOSPARC_PROJECT_DIR_PREFIX	The prefix to add to a project directory name on the filesystem when it is created.	CS-
CRYOSPARC_SLACK_WEBHOOK_URL	If set, CryoSPARC makes an HTTP request to this URL each time a job's status changes with some job metadata encoded in JSON	-
CRYOSPARC_SSD_CACHE_LIFETIME_DAYS	Whenever a job requires SSD cache, it automatically checks for and removes files that haven't been accessed in more than the number of days specified by this variable. Note: Files may remain on the SSD for longer than this amount since they only get cleaned up when a job runs	30
REQUESTS_CA_BUNDLE	May be required for connection to the CryoSPARC license verification server on systems with outdated Certificate-Authority files or that filter HTTPS requests through a proxy. Specify a path to a file or folder that contains the certificates.	-
CRYOSPARC_HEARTBEAT_SECONDS	CryoSPARC jobs running on worker nodes regularly report their status to the master command server to indicate that they are still running and active. If a job fails to report for more than this number of seconds (e.g., due to stalling, a slow network or a silent error), CryoSPARC marks the job as failed. Increase for very busy/low-resource worker nodes or slow/unreliable connections between the master and worker nodes. Increasing may reduce heartbeat-related job failures.	180
CRYOSPARC_IGNORE_PORT_CONFLICTS	Ignore port conflicts when binding service ports.	false
CRYOSPARC_DB_MIN_SPACE_GB	Minimum free disk space required for MongoDB data directory.	5
CRYOSPARC_API_PROCS	Number of API service processes (1–8).	3
CRYOSPARC_RETAIN_QUEUE_POSITION_SECONDS	When clearing and re-queuing a job, this value is the window of time for which the job will retain its position in the CryoSPARC instance job queue. i.e. The job will still count as being scheduled from when it was first queued for CRYOSPARC_RETAIN_QUEUE_POSITION_SECONDS long since it was cleared. After the window passes without re-queueing, the job will lose its position in the queue, and the next time it is queued it will schedule as normal.	0
CRYOSPARC_LIVE_RETRY_TIMEOUT_SECONDS	Length of time to wait before restarting a failed worker job in CryoSPARC Live	30
CRYOSPARC_LIVE_RETRY_ATTEMPTS	Number of attempts to retry a failed worker job in CryoSPARC Live. If a worker job fails more times than this value, the job will not be automatically restarted.	3
CRYOSPARC_AUTO_EXPORT_INSTANCE_CONFIG_ENABLE	Enables automatic instance configuration exports.	true
CRYOSPARC_AUTO_EXPORT_INSTANCE_CONFIG_INTERVAL_HOURS	Interval for the automatic export of instance configurations.	1
CRYOSPARC_AUTO_EXPORT_INSTANCE_CONFIG_DIR	The location which instance configurations will be automatically exported to.	$ROOT_DIR/run
CRYOSPARC_DISABLE_EXTERNAL_REQUESTS	Disables application requests to external HTTPS resources used for information modules in the homepage including EMPIAR, EMDB, Discuss, CryoSPARC tutorials, and the CryoSPARC changelog.	false
CRYOSPARC_INSECURE	Disables HTTPS secure connections and enables HTTP insecure connections, for connections to CryoSPARC license servers.	false
CRYOSPARC_JOB_LAUNCH_TIMEOUT_SECONDS	Timeout for launching CryoSPARC jobs on a remote worker. A launched job that does not start within this timeout will fail.	15

Note: This file includes the following environment variables that are specified at installation time:

• CRYOSPARC_LICENSE_ID

• CRYOSPARC_MASTER_HOSTNAME

• CRYOSPARC_DB_PATH

• CRYOSPARC_BASE_PORT

cryosparc_worker/config.sh

No restart is required after changing this file.

Variable	Description	Default Value
CRYOSPARC_CACHE_NUM_THREADS	(v4.3+) Number of threads to use during caching when copying particle .mrc files from the project directory to the cache directory. Set to 1 to disable threading and copy files sequentially. #leveraging-multiple-threads-to-copy-particles	2
CRYOSPARC_CACHE_LOCK_STRATEGY	(v4.5+) Distributed locking strategy to use when multiple running jobs access the SSD cache simultaneously. Set to file to use a file-system POSIX lock. Set to master to use the CryoSPARC master as a broker. Use the master strategy for caches on distributed file systems such as GPFS and BeeGFS where POSIX locks are disabled or unavailable.	master
CRYOSPARC_CACHE_COPY_BUFFER_SIZE_MB	Size of the buffer used when copying files to the CryoSPARC cache location.	8
CRYOSPARC_CACHE_MAX_ATTEMPTS	Number of attempts to retry using the CryoSPARC cache. The job will fail if the number of attempts exceeds this value.	1
CRYOSPARC_CLIENT_TIMEOUT	How many seconds to wait for network requests between CryoSPARC worker/master processes before timing out with an error	300
CRYOSPARC_IO_URING	Set to false to force-disable io_uring for fast disk read operations during jobs. May be required for some older operating systems or systems with an incorrect io_uring implementation.	true
CRYOSPARC_NO_PAGELOCK	By default, CryoSPARC uses the CUDA driver's pagelocked_empty function to allocate GPU memory. This causes CUDA-driver errors on some systems. Set this variable to true to use numpy.empty	false
CRYOSPARC_SSD_PATH	Set this variable to override the SSD cache path provided when you installed the worker. Useful if the SSD cache path is generated by your cluster as an environment variable when the job is scheduled. Important: The worker must be connected with a stub SSD path for this to take effect, e.g., "cache_path": "/tmp" in cluster_config.json	-
CRYOSPARC_TIFF_IO_SHM	(available in CryoSPARC versions 3.2 through 4.5.3) When reading TIFF or EER movie files, CryoSPARC reads the entire file into memory before decompressing. This significantly improves performance on some networked file systems but uses more memory. Set to false to perform decompression directly from disk	true
CRYOSPARC_IO_FD_LIMIT	Limit of how many open file descriptors CryoSPARC can create when running jobs.	-

Note: This file includes the following environment variables that are specified at installation time:

• CRYOSPARC_LICENSE_ID

• CRYOSPARC_CUDA_PATH

• CRYOSPARC_USE_GPU