Software Updates

How to get the latest cryoSPARC features and fixes or roll back to a previous version.

Software updates

We release new updates to cryoSPARC approximately every 6-8 weeks. The cryoSPARC Dashboard shows update notifications:

Look for the new version notification in the bottom status bar of the cryoSPARC dashboard.

You can also sign up for the newsletter to receive update notifications with an overview of new features.

Before you update: complete or kill running jobs

Before installing an update, wait for all presently running jobs to complete, or kill them from the Resource Manager.

IMPORTANT. Before you update your instance, we recommend making a backup of your database.

Checking for updates

Unless otherwise noted:

  • Log in to the workstation or remote node where cryosparc_master is installed.

  • 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 bash

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
Update available!

You can also use cryosparcm update --list to get a full list of available versions (including old versions in case you would like to downgrade).

$ cryosparcm update --list
CryoSPARC current version v2.14.0
update starting on Wed Mar 18 12:11:42 EDT 2020
Available versions:
To install a specific version, use
$ cryosparcm update --version=vXX.YY.ZZ[-branchname]

Installing automatic updates

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

cryosparcm update

Cluster workers are not updated automatically. See the "Manual Cluster Updates" section below

This commands executes the following:

1. Runs an automatic master update

  • Shuts down the running cryoSPARC instance

  • Downloads new the master (cryosparc_master.tar.gz) and worker (cryosparc_worker.tar.gz) releases

  • 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.

2. Runs automatic worker updates

Once the master update is complete, master starts up and automatically updates registered workers:

  • Transfers the worker release cryosparc_worker.tar.gz to each worker node via scp

  • 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.

Manual Cluster Updates

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 cryosparc_worker.tar.gz orcryosparc2_worker.tar.gz

Copy this file (via scp) to cluster worker's installation directory. It should be in the same directory as the bin and deps folders. Navigate to the installation directory and run

If you're updating from cryoSPARC v2 to v3, the downloaded file is calledcryosparc2_worker.tar.gz. Do not change this file name when you copy it into the worker directory.

bin/cryosparcw update

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.

Update or roll back/downgrade to a specific 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

Use cryosparcm update --list to see the list of available versions. Substitute the vX.Y.Z in the command above with one of the results.

Forced update

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.

Verify successful update or installation (optional)

CryoSPARC provides a method of verifying that all components of an installation are correctly working and set up. See the Extensive Workflow guide here.

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

Apply Patches

The cryoSPARC team periodically releases patches for specific versions of cryoSPARC that fix bugs which do not require a full formal software update.

To check for available patches, run

cryosparcm patch --check

Before applying patches, ensure cryoSPARC is running:

cryosparcm start

Apply the patch with one of the following strategies:

Single Workstation
Master Node
Single Workstation

Automatically install all patches:

cryosparcm patch
Master Node

Automatically install patches on the master and connected dedicated worker nodes

cryosparcm patch

From the master node, run

cryosparcm patch --download

This downloads master and worker tarballs to the cryosparc_master installation directory. Follow the resulting a set of instructions for installing both patch files.

The instructions will involve the following:

  • Install the master patch file with cryosparcm patch --install

  • Upload the downloaded patch to worker nodes

  • From each worker node, run bin/cryosparcw patch

Finally, reload cryoSPARC and refresh job types:

cryosparcm cli "reload()"
cryosparcm cli "refresh_job_types()"