Software Updates and Patches
How to get the latest CryoSPARC features and fixes or roll back to a previous version.
When we release a new version of CryoSPARC, the Dashboard will display an update notification.
In CryoSPARC v4.0+, the update notification is displayed at the top of the Dashboard:
In CryoSPARC v3, the update notification is displayed in the footer:
Look for the new version notification in the bottom status bar of the cryoSPARC dashboard.
We also periodically release patch updates for CryoSPARC, to address issues outside of normal updates. To learn more about patches, see: https://guide.cryosparc.com/setup-configuration-and-management/software-updates#apply-patches
Before installing an update or downgrading to a previous version, wait for all presently running jobs to complete, or kill them from the Resource Manager. We also highly recommend making a backup of your database as described below.
In CryoSPARC v4.0+, you can use the Maintenance Mode feature to pause new jobs during an update:
Unless otherwise noted:
- Log in to the workstation or remote node where
- Use the same non-root UNIX user account that runs the cryoSPARC process and was used to install cryoSPARC.
- Run all commands on this page in a terminal running
Run this command to check for CryoSPARC updates.
cryosparcm update --check
This checks online for available updates and indicates whether an update is available.
$ cryosparcm update --check
CryoSPARC current version v2.15.0
update starting on Wed Mar 18 12:09:52 EDT 2020
current version v2.15.0
new version v3.0.0
You can also use
cryosparcm update --listto get a full list of available versions (including old versions in case you would like to downgrade).
$ cryosparcm update --list
CryoSPARC current version v4.1.0
update starting on Wed Mar 18 12:11:42 EDT 2020
To install a specific version, use
$ cryosparcm update --version=vXX.YY.ZZ[-branchname]
Perform the following actions when installing the latest version of CryoSPARC.
To begin automatic master and non-cluster worker updates with the newest available version of CryoSPARC, run
Cluster workers are not updated automatically. See the "Manual Cluster Updates" section below
This commands executes the following:
- Downloads the new master (
cryosparc_master.tar.gz) and worker (
cryosparc_worker.tar.gz) update packages if
--skip-downloadwas not specified
- Shuts down the running CryoSPARC instance
- Extracts and installs the master release
- If dependencies have changed, automatically re-installs these
CryoSPARC releases include many compressed files; the extraction step may take several minutes on slower disks.
Once the master update is complete, master starts up and automatically updates registered workers:
- Transfers the worker release
cryosparc_worker.tar.gzto each worker node via
- Extracts and installs the worker release
- Updates dependencies
If multiple standalone worker nodes are registered that all share the same worker installation, the update is only applied once.
Cluster installations do not update automatically because not all clusters have internet access on worker nodes.
Once the automatic update above is complete, navigate to the CryoSPARC master installation directory via command-line. Look for the latest downloaded worker release, named
Copy this file (via
scp) to cluster worker's installation directory. It should be in the same directory as the
depsfolders. Navigate to the installation directory and run
If you're updating from cryoSPARC v2 to v3, the downloaded file is called
cryosparc2_worker.tar.gz. Do not change this file name when you copy it into the worker directory.
This updates the worker at the current location with the given release file.
cryoSPARC does not allow running mismatched versions of master and worker releases. If you see this error:
Version mismatch! Worker and master versions are not the same. Please update.
Then re-install your cryoSPARC master and worker and check they are on the same version.
Follow this section to install or update/downgrade to a specific release of CryoSPARC.
Steps are as described above, but with this command instead
cryosparcm update --version=vX.Y.Z
cryosparcm update --listto see the list of available versions. Substitute the
vX.Y.Zin the command above with one of the results.
For instructions on updating an existing CryoSPARC v3.x instance to v4.0, please see: Guide: Updating to CryoSPARC v4
If your CryoSPARC instance is running v4.0.0 and later, the oldest version of CryoSPARC you can downgrade to is v3.4.0. For more information, see Downgrading from v4
Follow this section when a cryoSPARC install or update process fails part-way, or if CryoSPARC cannot start after following the Troubleshooting steps.
This removes CryoSPARC and installs the latest available version, bypassing all file and dependency checks.
On the master node run
cryosparcm update --override
Then on each worker node run
bin/cryosparcw update --override
You cannot specify a version to install when overriding the update manager. Only the latest version of cryoSPARC will be installed.
Use the command line flag
cryosparcm updatecommand to perform a full update of CryoSPARC using the update packages already inside the
cryosparc_masterdirectory. This command can be run after manually downloading the update packages using
cryosparcm update --download-only.
cryosparcm update --skip-download
Use the command line flag
cryosparcm updatecommand to only download the update packages and not perform a full update of CryoSPARC. This can be helpful if your internet connection is slow, and you'd like to limit CryoSPARC's downtime. This option can be used to download any version of CryoSPARC available (use
cryosparcm update --listto see the list of available versions).
You can then use
cryosparcm update --skip-downloadto perform a full update using the downloaded update packages.
cryosparcm update --download-only# downloads the latest update packages
cryosparcm update --version=v4.1.0 --download-only# downloads the update packages corresponding to
CryoSPARC provides two methods of verifying that all components of an installation are correctly working and set up.
The first method is to run
cryosparcm test installand
cryosparcm test workersvia the command line. For more information, see Guide: Installation Testing with cryosparcm test
This automatic workflow executes all steps in the T20S Introductory Tutorial and verifies the following system components:
- CryoSPARC system and license installation
- Worker/Cluster configuration
- GPU and CUDA driver installation
- SSD caching
We periodically releases patches for specific versions of CryoSPARC to fix bugs which do not require a full formal software update. Subscribe to the CryoSPARC Newsletter to receive an email when we release a patch.
Patches for a specific CryoSPARC version are cumulative:
- One may apply the latest patch without having applied earlier patches.
- After application of the latest patch, application of an earlier patch is not needed and should not be attempted.
To check for available patches, run
cryosparcm patch --check
Before applying patches, ensure CryoSPARC is running:
Apply the patch with one of the following strategies (table):
If a cluster is connected, use the cluster installation instructions even if CryoSPARC was initially installed in workstation or master/worker mode
Automatically install all patches:
Automatically install patches on the master and connected dedicated worker nodes
From the master node, run
cryosparcm patch --download
This downloads master and worker tarballs to the
cryosparc_masterinstallation directory. Follow the resulting set of instructions for installing both patch files.
The instructions will involve the following:
- Install the master patch file with
cryosparcm patch --install
- Copy or upload the downloaded
cryosparc_worker_patch.tar.gzpatch into the
- Inside the
Depending on your cluster setup, either install the patch once in the
cryosparc_workerdirectory shared by all cluster nodes or repeatedly for each cluster node that hosts an independent
Finally, reload CryoSPARC and refresh job types:
cryosparcm cli "reload()"
cryosparcm cli "refresh_job_types()"