# Software Updates and Patches {% hint style="warning" %} CryoSPARC v5 BETA was released January 27, 2026. For updating from CryoSPARC v4 to CryoSPARC v5 for the first time, see the [CryoSPARC v5 compatibility requirements and update instructions here](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-updating-to-cryosparc-v5). {% endhint %} ## Software updates ### New versions When we release a new version of CryoSPARC, the Dashboard will display an update notification. In CryoSPARC v4 and v5, 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.](https://1916621962-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M7DGv3GkRvGGpbVPCgg%2Fsync%2F95888c2bee3fd47a217830b62c4c75799fa738d3.png?generation=1589377614685011\&alt=media) You can [**sign up for the newsletter**](https://cryosparc.com/#newsletter) to receive an email when we release a new update or patch. ### Patches We also periodically release patch updates for CryoSPARC, to address issues outside of normal updates. To learn more about patches, see: {% embed url="" %} ## Before you update or downgrade {% hint style="warning" %} For updating from CryoSPARC v4 to CryoSPARC v5 for the first time, see the [CryoSPARC v5 compatibility requirements and update instructions here](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-updating-to-cryosparc-v5). {% endhint %} ### 1. Confirm sufficient storage capacity During the update, downloaded packages will require *additional* storage of approximately 6 gigabytes in the `cryosparc_master/` directory and 5 gigabytes in the `cryosparc_worker/` directory (for CryoSPARC version 4.7+). If `cryosparc_master/` and/or `cryosparc_worker/` are stored on the same volume as the CryoSPARC database, one must additionally ensure that the downloaded update packages will not fill up storage needed for the database. {% hint style="warning" %} Failure to ensure sufficient storage may result in * a failed software update * a broken software installation * when installation directories are stored on the same volume as the CryoSPARC database, a corrupt database {% endhint %} ### 2. Complete or \`kill\` running jobs Before you update your instance, 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. {% hint style="danger" %} **IMPORTANT.** Before you update your instance, we recommend making a [**backup of your database.**](https://guide.cryosparc.com/setup-configuration-and-management/management-and-monitoring/cryosparcm#cryosparcm-backup) {% endhint %} In CryoSPARC v4.0+, you can use the Maintenance Mode feature to pause new jobs during an update: {% content-ref url="software-system-guides/guide-maintenance-mode-and-configurable-user-facing-messages" %} [guide-maintenance-mode-and-configurable-user-facing-messages](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-maintenance-mode-and-configurable-user-facing-messages) {% endcontent-ref %} ### 3. Create a backup of the database {% hint style="danger" %} **IMPORTANT.** Before you update your instance, we recommend making a [**backup of your database.**](https://guide.cryosparc.com/setup-configuration-and-management/management-and-monitoring/cryosparcm#cryosparcm-backup) {% endhint %} ### 4. *Completely* shutdown CryoSPARC (with confirmation) {% hint style="warning" %} Incomplete shutdown of the CryoSPARC instance during updates is a known cause for update failures. Follow the sequence for a [*complete* shutdown](https://guide.cryosparc.com/troubleshooting#incomplete-cryosparc-shutdown) of the CryoSPARC instance. {% endhint %} ## Checking for updates {% hint style="warning" %} 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` {% endhint %} Run this command to check for CryoSPARC updates. ``` cryosparcm update --check ``` This checks online for available updates and indicates whether an update is available. ```bash $ 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 v4.1.0 update starting on Wed Mar 18 12:11:42 EDT 2020 Available versions: v2.0.18 v2.0.20 v2.0.23 ... v4.0.2 v4.0.3 v4.1.0 To install a specific version, use $ cryosparcm update --version=vXX.YY.ZZ[-branchname] ``` ## Installing automatic updates {% hint style="warning" %} For updating from CryoSPARC v4 to CryoSPARC v5 for the first time, see the [CryoSPARC v5 compatibility requirements and update instructions here](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-updating-to-cryosparc-v5). {% endhint %} 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 ```bash cryosparcm update ``` {% hint style="warning" %} Cluster workers are *not* updated automatically. See the "Manual Cluster Updates" section below {% endhint %} This commands executes the following: #### 1. Runs an automatic master update * Downloads the new master (`cryosparc_master.tar.gz`) and worker (`cryosparc_worker.tar.gz`) update packages if `--skip-download` was 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. #### 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` or`cryosparc2_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 {% hint style="info" %} 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. {% endhint %} ``` bin/cryosparcw update ``` This updates the worker at the current location with the given release file. {% hint style="info" %} 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. {% endhint %} ## Update or roll back/downgrade to a specific version Follow this section to install or update/downgrade to a specific release of CryoSPARC. Please see [**Before you update or downgrade**](#before-you-update-or-downgrade-complete-or-kill-running-jobs). 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. {% hint style="danger" %} For instructions on updating an existing CryoSPARC v3.x instance to v4.0, please see: [guide-updating-to-cryosparc-v4](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-updating-to-cryosparc-v4 "mention") {% endhint %} {% hint style="danger" %} 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](https://guide.cryosparc.com/software-system-guides/guide-updating-to-cryosparc-v4#downgrading "mention") {% endhint %} ## Forced update Follow this section when a cryoSPARC install or update process fails part-way, or if CryoSPARC cannot start after following the [**Troubleshooting**](https://guide.cryosparc.com/setup-configuration-and-management/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 ``` {% hint style="info" %} You cannot specify a version to install when overriding the update manager. Only the latest version of cryoSPARC will be installed. {% endhint %} ## Skip Downloading Update Packages During Update Use the command line flag `--skip-download` with the `cryosparcm update` command to perform a full update of CryoSPARC using the update packages already inside the `cryosparc_master` directory. This command can be run after manually downloading the update packages using `cryosparcm update --download-only`. For example: `cryosparcm update --skip-download` ## Manually Download Update Packages Use the command line flag `--download-only` with the `cryosparcm update` command 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 --list` to see the list of available versions). You can then use `cryosparcm update --skip-download` to perform a full update using the downloaded update packages. For example: `cryosparcm update --download-only` # downloads the latest update packages `cryosparcm update --version=v4.1.0 --download-only` # downloads the update packages corresponding to `v4.1.0` ## Verify successful update or installation (optional) 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 install` and `cryosparcm test workers` via the command line. For more information, see [guide-installation-testing-with-cryosparcm-test](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-installation-testing-with-cryosparcm-test "mention") The second method is to run the Extensive Workflow job. [See the Extensive Workflow guide here.](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/tutorial-verify-cryosparc-installation-with-the-extensive-workflow-sysadmin-guide) This automatic workflow executes all steps in the [T20S Introductory Tutorial](https://guide.cryosparc.com/guides-for-v3/cryo-em-data-processing-in-cryosparc-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 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**](https://cryosparc.com/#newsletter) to receive an email when we release a patch. {% hint style="info" %} 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. One may apply the latest patch for a given CryoSPARC version even if an earlier patch for that version has previously been applied. {% endhint %} 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 (table): {% hint style="info" %} If a cluster is connected, use the cluster installation instructions even if CryoSPARC was initially installed in workstation or master/worker mode {% endhint %} {% tabs %} {% tab title="Single Workstation" %} Automatically install all patches: ``` cryosparcm patch ``` {% endtab %} {% tab title="Master Node" %} Automatically install patches on the master and connected dedicated worker nodes ``` cryosparcm patch ``` {% endtab %} {% tab title="Cluster" %} From the master node, run ``` cryosparcm patch --download ``` This downloads master and worker tarballs to the `cryosparc_master` installation 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.gz` patch into the `cryosparc_worker` directory * Inside the `cryosparc_worker` directory, run `bin/cryosparcw patch` Depending on your cluster setup, either install the patch once in the `cryosparc_worker` directory shared by all cluster nodes or repeatedly for each cluster node that hosts an independent `cryosparc_worker` directory. {% endtab %} {% endtabs %} Finally, restart CryoSPARC: ``` cryosparcm restart ```