Guide: Updating to CryoSPARC v5 (BETA)

CryoSPARC v5 is backwards compatible with v4. The update process includes new validation steps that may take some time, up to one hour for larger instances.

As of January 27 2026, CryoSPARC v5 BETA is currently released as a public beta version.

Updating to CryoSPARC v5 from v4

In v5, CryoSPARC’s underlying software system has been completely redesigned for stability, scalability, and to enable future developments. The new system adds strong validation and consistency guarantees for CryoSPARC database contents, minimizing the likelihood of errors and issues.

CryoSPARC v5 is backwards compatible with v4 versions, meaning:

• A v4.0+ instance can be upgraded to v5, and also downgraded back to v4.4+ if needed

• Projects detached from v4 instances can be attached to v5 instances, and vice versa

Updating to CryoSPARC v5 will perform a validation and upgrade of all database contents and will take some time, up to one hour for large instances. The user interface will not be available during the update process.

In the sections below you will find:

• Compatibility requirements including OS and NVIDIA Driver versions for CryoSPARC v5

• A walkthrough of the update process that includes validation of database contents

• Steps and commands to update from CryoSPARC v4 to CryoSPARC v5

• Steps and commands to downgrade from CryoSPARC v5 to CryoSPARC v4

Compatibility Requirements

• CryoSPARC Versions: You must be running CryoSPARC v4.0+ to update to v5. Updating from CryoSPARC v3 or below is not supported. For older instances, please update to a v4 version first, then update to v5. Once v5 is installed, you can downgrade to CryoSPARC versions v4.4+; If you need to downgrade further back than v4.4, downgrade to v4.7 first, then downgrade to the older version.

• Operating System: For CryoSPARC v5, the operating system must support GLIBC 2.28 or greater. Therefore, the oldest compatible operating systems are Rocky/RHEL 8 and Ubuntu 20.04. However, Ubuntu 22.04 or newer is recommended.

• NVIDIA Driver: CryoSPARC v5 requires NVIDIA driver version 570.26 or newer. Note that NVIDIA Blackwell devices are only compatible with the open driver. CryoSPARC v5 uses CUDA 12.8 which drops support for NVIDIA GPUs with compute capability 3.5 (Kepler). Only GPUs with compute capability 5.0 (Maxwell) to 12.0 (Blackwell) are supported.

• cryosparc-tools: A new, backwards compatible version of cryosparc-tools for scripting with v5 is available; see details here. Scripts written with previous versions will continue to function as before.

• CryoSPARC CLI: CryoSPARC v5 introduces a new improved command line interface that is not compatible with v4 cli commands. Scripts that used v4 cli commands will need to be updated, including for managing CryoSPARC Live sessions.

Walkthrough of Update Process

CryoSPARC v5 includes new database validation checks that ensure consistency. For this reason, when updating from v4 to v5, a database upgrade step will be automatically performed during the update process. This step confirms the validity of all existing documents in the CryoSPARC database (e.g. users, projects, jobs) and potentially could take up to an hour for large instances. The database upgrade step runs in the command line as part of the update command; the CryoSPARC user interface will not be available while it is in progress. In rare cases, the database upgrade step may find some data in the database that is invalid (for example, if a user had manually modified the database in an inconsistent way in the past).

The database upgrade will proceed in two phases:

1. Dry run validation phase (no modifications are made to the database during this phase):

   • Database contents are validated, including users, scheduler targets, projects, workspaces, jobs, sessions, and exposures. The validation process will keep track of any invalid data that it finds that it can fix automatically. These pending fixes will be written to a validation JSON file, e.g.: cryosparc_master/run/validation_results_2025_07_30_23h50.json.

   • If the validation phase finds invalid database contents within a project (i.e., jobs, workspaces, sessions) then the user is given the option to detach the corresponding invalid project as part of the next phase. No data on disk will be deleted, and detached projects can be attached to another CryoSPARC v4 instance. If the user does not wish to detach invalid projects, the upgrade is aborted: downgrade to v4 using the instructions below.

   • If the validation phase finds other invalid database content that it cannot fix, the upgrade is aborted: downgrade to v4 using the instructions below. The update process will ask if it is okay to upload the validation JSON file to Structura to helps us identify and fix any issues.

2. Upgrade write phase (changes are written to the database and disk):

   • Upgrade proceeds to make the changes that were validated in the previous step. Change results are written to an upgrade JSON file, e.g.: cryosparc_master/run/upgrade_results_2025_07_30_23h50.json.

Once the update is complete, CryoSPARC v5 starts and is ready for use.

Steps and commands to update from v4 to v5

1. Ensure all compatibility requirements are met.

2. Follow the standard Before you update or downgrade steps to ensure you have sufficient disk space, have killed running jobs, completely shut down CryoSPARC, and created a backup of the CryoSPARC database.

3. Run cryosparcm update

   1. This command will update to the latest CryoSPARC v5 release. It will download the new version, update dependencies, then proceed with the database upgrade step described above before starting the CryoSPARC instance.

Downgrade from CryoSPARC v5 to v4

Run cryosparcm update --version v4.7.1 (or replace the version with another version ≥ v4.4.0, if desired). The instance can be started and run normally after this.

Note that it is not possible to downgrade from v5.0 directly to any version older than v4.4. If you need to downgrade further back than v4.4, downgrade to v4.7 first then downgrade to the older version.