Making Boltz Structure Predictions in ChimeraX

Tom Goddard
April 23, 2025, updated May 30, 2025

ChimeraX can run the Boltz-1 structure prediction method to compute atomic structures of proteins and nucleic acids, including modified residues, ligands, ions and solvent on your laptop or desktop computer. See the demonstration video. The method is inspired by AlphaFold 3 and described in the following preprint and is fully open source with a very permissive MIT license.

      Boltz-1: Democratizing Biomolecular Interaction Modeling
      Jeremy Wohlwend, Gabriele Corso, Saro Passaro, Mateo Reveiz, Ken Leidal,
        Wojtek Swiderski, Tally Portnoi, Itamar Chinn, Jacob Silterra, Tommi Jaakkola, Regina Barzilay
      bioRxiv 2024.11.19.624167; doi: https://doi.org/10.1101/2024.11.19.624167

A ChimeraX graphical user interface (menu Tools / Structure Prediction / Boltz) and ChimeraX command (boltz) are provided to make predictions. The latest version of this documentation is available online.

Boltz structure predictions use a lot of memory and compute resources on your computer that limits the size of the structure that can be predicted. See the run times section below for example run times and size limits.

Mac. It works well on Mac M-series (M1,M2,M3,M4) laptop and desktop computers predicting small 100 residue structures in 1 minute and up to 1200 residues in about 15 minutes with 32 GB of memory. With 16 GB of memory it can only predict about 350 amino acids taking about 5 minutes, with larger predictions running out of memory.

Nvidia GPUs on Windows and Linux. Nvidia GPUs on Windows and Linux computers also provide good performance. On Linux with an Nvidia GPU with 24 GB of graphics memory (e.g. Nvidia RTX 3090 or 4090) it can predict about 1000 residues in about 4 minutes, larger sizes run out of memory, although using the 16-bit floating point option can extend the range to 1400 residues in about 10 minutes but with possible reduction in accuracy. Testing on Windows with less GPU memory, 12 GB (e.g. Nvidia RTX 4070) predicts up to 700 residues or 1000 with 16-bit floating point. On Windows with 8 GB of GPU memory (e.g Nvidia RTX 3070) predictions of 500 residues or 700 with 16-bit floating point are relatively fast. Large predictions on Nvidia GPUs on Linux run out of memory and fail. On Windows the prediction will fallback to using CPU memory allowing larger structure predictions but taking immensely longer run times (10-30 times longer).

Intel CPU. Predictions only utilizing an Intel CPU are very slow, for example 1.5 hours for 900 residues. Expected size limits are about 350 residues with 16 GB, 1000 residues with 32 GB, and about 1600 residues with 64 GB. Run time is expected to increase as the square of the number of residues.

When you first start the Boltz tool within ChimeraX (menu Tools / Structure Prediction / Boltz) it will show a button Install Boltz. Boltz is a large software package, taking about 1 Gbyte of disk space and uses the Torch machine learning package. It also requires the neural network weights (3.3 Gbytes) and PDB Chemical Component Dictionary (CCD, 0.3 Gbytes) to make predictions. Downloading and installing all of these files will take 10 minutes or more depending on network speed and install the software in your home directory in ~/boltz and the network weights and CCD in ~/.boltz.

The ChimeraX boltz install command can also be used to do this one time installation.

Menu of molecular components

To predict a structure made up of proteins, nucleic acids and small molecules you first specify all the molecular components. Choose entries from the Add menu and press the Add button to add them to your assembly specification in the table below. You can specify component molecules in several ways.

• Protein and nucleic acids can be specified by choosing chains open models.
• Sequences of one letter codes for proteins (20 amino acids) or DNA or RNA can be pasted in.
• UniProt database identifiers can be give for proteins.
• Ligands, ions and solvent can be specified by 3-letter or 5-letter chemical component dictinary codes (e.g. ATP or HEM).
• Small molecules can be specified by SMILES strings.

Hemoglobin dimer prediction (blue) aligned to experimental structure PDB 1hho

Predicted aligned error

Components can be added multiple times to have more instances of that molecule in the assembly. Press the Predict button after the assembly is completed by adding each component to start the prediction. A Stop button will be shown while the prediction runs to terminate the prediction, discarding the partial computation so you can start another prediction.

The results are put in a new folder on your desktop named by default boltz_assembly_name where the prediction name can be specified at the top of the ChimeraX Boltz panel. Using the Options described below you can change where the result files are placed.

Predictions for small assemblies, for example 500 residues and ligand atoms, take one to several minutes depending on the computer (e.g. Nvidia GPU vs CPU only). The run in the background (a separate process) so ChimeraX can continue to be used while the calculation runs. The predicted structure will be opened in ChimeraX when the calculation completes. If the assembly specification involved proteins or nucleic acids specified using chains of open models, the predicted structure will be aligned (using matchmaker) to the open model for the first such component.

Coloring

The prediction will be colored using the standard AlphaFold pLDDT type of coloring where blue indicates high confidence, yellow and red moderate to low confidence.

Predicted aligned error

Finer grained estimates of prediction confidence can be displayed by pressing the Error Plot button to show the predicted aligned error.

Here are run times for several desktop and laptop computers for predicting various size molecular assemblies from the Protein Databank using Boltz version 1.0.0 (May 25, 2025 source) without diffusion steering potentials. Another table compares Boltz 1.0.0 to Boltz 0.4.1 and timings of 16-bit floating point and diffusion steering.

Boltz prediction times in minutes. Tokens is number of standard polymer residues plus ligand atoms.

• Mac M1 16 GB - Mac Mini, 8 core GPU, euclid.cgl.ucsf.edu
• Mac M1 Max 32 GB - MacBook Pro 32 core GPU, Tom's laptop
• Mac M2 Ultra 64 GB - Mac Studio 60 core GPU, descartes.cgl.ucsf.edu
• Linux i9 CPU - cpu i9-13900K (24 cores) 64 GB (DDR5 5200MHz), minsky.cgl.ucsf.edu
• Linux Nvidia 4090 - VRAM 24 GB, cpu i9-13900K (24 cores) 64 GB (DDR5 5200MHz), minsky.cgl.ucsf.edu
• Windows i7 CPU - cpu i7-12700K (12 cores) 64 GB DDR5 4000MHz, vizvault.cgl.ucsf.edu
• Windows Nvidia 3070 - Windows 11, VRAM 8 GB, PCIe 4.0, cpu i7-12700K (12 cores) 64 GB DDR5 4000MHz, vizvault.cgl.ucsf.edu

Performance notes

Mac GPU acceleration. The reported Mac performance is for Mac M1/M2/M3/M4 series GPUs. Boltz uses machine learning package torch which has GPU acceleration called Metal Performance Shaders (MPS) on these Mac M series GPUs which have speed up to 2-3x slower than an Nvidia 4090 but with the advantage that the Mac can handle larger molecular systems using the unified computer memory (e.g. 32 or 64 GB). With 16 GB prediction size is limited to 350 residues. Older Mac Intel machines do not have GPU acceleration in Torch and run at speeds similar to Windows Intel CPU-only predictions.

Windows Nvidia GPU performance. The above table shows a significant slow-down in predictions beyond about 600 residues on Windows with Nvidia 3070 (8 GB) and 4070 (12 GB) graphics. This is probably because the GPU memory is insufficient for larger structures and the machine learning toolkit falls back to a mix of CPU and GPU calculation. Notice that the 4070 GPU took more time than the 3070 GPU for large structures probably because the CPU on the 4070 machine (i5-6700K) is significantly slower than the CPU on the 3070 machine (i7-12900K).

Linux Nvidia GPU out of memory. On Linux Nvidia 4090 with 24 GB of GPU memory the maximum prediction appears to be about 1000 residues plus ligand atoms before an "out of memory" error occurs. This contrasts with Windows where Torch appears to fallback to using CPU and not run out of GPU memory.

Optimizing for larger structures with Nvidia GPU. Structure predictions 40% larger are possible by using 16-bit floating point (bfloat16) on Nvidia GPUs instead of float32 for boltz weights and activations. Prediction speed is about the same. I tested this on Nvidia 4090 on Linux and it was able to predict 9fz5 (1025 tokens) in 3 minutes and 8sa0 (1371 tokens) in 5 minutes. I have not seen a reduction in accuracy. Details in ChimeraX ticket #17555. This is available as the 16-bit floating point option in the ChimeraX Boltz Options panel or the float16 option of the ChimeraX boltz predict command.

Pressing the Options button shows additional settings for boltz predictions.

• Results directory: You can change where the results are placed. The path contains "[name]" which is replaced with the prediction name.
• Number of predictions: The default number of predicted structures is 1, but you can request more to get an ensemble of structures that usually have small variations.
• Compute device: The computation can run on Nvidia GPUs or Mac M series GPUs and complete faster than CPU-only calculations. The default setting tries to uses the GPU if available.
• Predict larger structures with Nvidia 16-bit floating point: Use 16-bit floating point calculations (bfloat16) instead of 32-bit to save memory and prediction structures up to 40% larger on Nvidia GPUs.
• Use steering potentials. May be more accurate, but slower: Use Boltz 1x diffusion steering potentials which are claimed to produce more accurate predictions but runs slower (1.25x on Nvidia, 2.5x on Mac).
• Use multiple sequence alignment cache: Boltz uses deep multiple sequence alignments for proteins that are computed using the Colabfold server. To avoid recomputing the alignments when you run predictions with the same proteins but different ligands ChimeraX caches those alignments in ~/Downloads/ChimeraX/BoltzMSA and the cached alignments will be used if available as long as this option enables using the cache.
• Boltz install location: Boltz is installed in a virtual Python environment contained in this folder.
• Save default options: Save the currently shown option settings as the defaults for future ChimeraX sessions.

Additional advanced options are available by using the ChimeraX boltz command.

The ChimeraX Boltz graphical interface runs a prediction by running the ChimeraX boltz command. That command is recorded in the ChimeraX Log panel, and looking at that command can help you understand the command options.

      boltz predict [sequences] [protein sequences] [dna sequences] [rna sequences]
         [ligands residue-spec] [excludeLigands ccd-codes]
         [ligandCcd ccd-codes] [ligandSmiles smiles-string]
         [name prediction-name] [resultsDirectory directory]
         [device default|cpu|gpu] [float16 true|false] [steering true|false]
         [samples n] [recycles n] [seed n]
         [useMsaCache true|false] [open true|false] [installLocation directory] [wait true|false]

Options descriptions

• sequences - Sequences can be specified using chain ids, UniProt identifiers, explicit strings of amino acid 1-letter codes, or ChimeraX sequence viewer ids.
• protein sequences - Like the previous sequences option only this explicitly excludes non-protein sequences in specifiers for open models. For example "protein #1" would not include any DNA/RNA chains of model #1. This option can be used more than once.
• dna sequences - Uses only DNA sequences from open model specifiers and treats explicit 1-letter code sequences as DNA. UniProt ids cannot be used. This option can be used more than once.
• rna sequences - Uses only RNA sequences from open model specifiers and treats explicit 1-letter code sequences as RNA. UniProt ids cannot be used. This option can be used more than once.
• ligands residue-spec - Specify ligands using residue specifiers for open models.
• excludeLigands ccd-codes - Exclude these CCD codes when interpreting the ligands option. By default it excludes ccd code "HOH", ie water.
• ligandCcd ccd-codes - Comma-separated list of 3 or 5-letter CCD codes. This option can be used more than once.
• ligandSmiles smiles-string - Comma-separated list of SMILES strings. This option can be used more than once.
• name prediction-name - Name of prediction used in the results folder name.
• resultsDirectory directory - Path to the results directory that will be created. "[name]" in the path will be replaced by the prediction name. If the folder already exists an numeric suffix _1, _2, _3... will be appended.
• device default | cpu | gpu - Whether to run the computation on GPU or CPU. The default setting chooses based on GPU availability and torch support for the GPU.
• float16 true | false - Whether to use 16-bit floating point (bfloat16) on Nvidia GPUs to allow prediction of larger structures (approximately 40% more residues). This may reduce prediction accuracy.
• steering true | false - Whether to use Boltz version 1x diffusion steering potentials. This is claimed to produce more accurate predictions but takes longer (1.25x on Nvidia, 2.5x on Mac) to run.
• samples n - Number of predictions. Default is 1. This is what Boltz calls "diffusion samples". Creating additional structures takes much less time than creating the first structure.
• recycles n - Number of passes through the neural net that derives spatial information from which structures will be computed. Defaults to 3. Better structures make result from 10 but runtime will be increased.
• seed n - Random numbers seed (integer) to initialize calculation. Runs with different seeds will give different results.
• useMsaCache true | false - Whether to use protein deep sequences alignments from the ChimeraX Boltz MSA cache in ~/Downloads/ChimeraX/BoltzMSA. Because the alignments for different proteins in an assembly are paired to match ones from the same organisms, using the cache requires that an assembly have the exact same set of proteins. It cannot use alignments computed for individual proteins from multiple different runs.
• open true | false - Whether to open the predicted structures when the prediction finishes. The structures will be aligned to an already open model if that open model was used (the first used) in specifying the assembly.
• installLocation directory - Where Boltz is installed. If specified this sets the default location used in future ChimeraX sessions.
• wait true | false - Whether ChimeraX should wait frozen while the prediction is computed or return immediately and allow ChimeraX use during the computation.

       boltz install [directory] [downloadModelWeightsAndCcd true | false] branch name

The boltz install command creates a Python virtual environment to install Boltz from PyPi. If no directory is specified then ~/boltz in the user's home directory is used. The directory will be created or if it already exists must be empty. It then downloads the Boltz network parameters and Chemical Component Dictionary to ~/.boltz. Finally it makes an index of the atom counts for each CCD code so that the ChimeraX Boltz interface can report the total number of tokens (residues plus ligand atoms) in an assembly in order to judge whether the computer has enough memory to make the requested prediction.

The install uses a fork of the Boltz repository https://github.com/RBVI/boltz. It uses git branch chimerax of this fork unless the branch option is specified in which case it installs the specified branch. The branch option is for testing new versions of Boltz.

The install process executes these commands to make the virtual environment and install Boltz. It uses the ChimeraX Python executable to create the virtual environment. Boltz will no longer work if ChimeraX is moved or deleted and will need to be reinstalled in that case. It will also no longer work if the boltz directory itself is moved since the boltz executable refers to the install location to find python.

The ChimeraX boltz install command creates a Python virtual environment and installs boltz and downloads the boltz weights and CCD database. On Windows it installs a version of torch with CUDA 12.6 support before installing boltz if Nvidia graphics is detected.

      python -m venv directory
      directory/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cu126  # On Windows with Nvidia GPU only.
      directory/bin/python -m pip install boltz
      directory/bin/python chimerax/site-packages/boltz/download_weights_and_ccd.py
    

• Structure size. Boltz uses a lot of memory and the amount of available memory limits the size of structures that can be predicted. For a computer with 32 Gbytes the size limit is roughly 1000 residues plus ligand atoms (called "tokens"). Consumer Nvidia GPUs with 8 or 12 GB of memory (e.g. RTX 3070) only handle 300-500 residues before using CPU memory on Windows that slows the prediction speed by 10-20 fold. On Linux it will not use CPU memory. Consumer Nvidia GPUs with 24 GB (RTX 3090 and RTX 4090) are able to predict 1000 tokens, or about 1400 with 16-bit floating point. Prediction size limits are perhaps the most important shortcoming of Boltz compared to AlphaFold 3 which handles memory more efficiently and is able to predict 5000 tokens with 80GB of GPU memory, about twice the size that Boltz can predict. A drawback of AlphaFold 3 is that it requires Linux and an Nvidia GPU in addition to various licensing restrictions. We hope in the future Boltz will optimize memory use to predict larger structures.
• Run time. The computation time increases as the square with the number of tokens. So a prediction with 3 times the number of residue and ligand atoms will take approximately 9 times longer to run.
• Nvidia GPU support on Windows. Installing Boltz will get a CUDA-enabled version of the torch machine learning package if it detects Nvidia graphics. It decides if you have Nvidia graphics by seeing if the file C:/Windows/System32/nvidia-smi.exe exists. Otherwise it gets a cpu-only version of torch. If you install an Nvidia graphics driver after installing Boltz you will have to reinstall Boltz to get the CUDA version. The installed torch is for CUDA 12.6 or newer. If your computer has a version of CUDA older than 12.6 but newer than 11.8 you can run the following commands in a Windows Command Prompt to install a CUDA 11.8 version of torch. For other CUDA versions refer to the Torch installation page for the correct pip install command.

  	  > cd C:\Users\username\boltz\Scripts
  	  > pip.exe uninstall torch
  	  > pip.exe install torch --index-url https://download.pytorch.org/whl/cu118

• Nvidia GPU support on Linux. On Linux the installed Boltz will work with CUDA 12.6 or newer if you have Nvidia graphics. If you have an older system CUDA version it may still work, or you can refer to the Torch installation page for the correct pip install command and replace torch with the following shell commands.

  	  $ cd ~/boltz/bin
  	  $ ./pip uninstall torch
  	  $ ./pip install torch --index-url https://download.pytorch.org/whl/cu118

• No covalently linked ligands. Although Boltz can predict covalently linked ligands I have not yet included that capability in the ChimeraX interface or command. Similarly post-translational modifications such as phosphorylation are not yet supported.
• No assigning chain identifiers. It can be helpful to assign chain identifiers (A,B,C...) to the different molecular components to match existing structures. Boltz is capable of this but the ChimeraX user interface does not currently allow it.
• MSA sequence alignments. Boltz uses the Colabfold MSA server (https://api.colabfold.com) for computing deep sequence alignments. This requires internet connectivity and is subject to outages it that server (located in Korea currently) is down. The sequence alignments are cached in ~/Downloads/ChimeraX/BoltzMSA so subsequent predictions with the same set of polymers can reuse the sequence alignment.

• May 28, 2025. Updated to Boltz-1x (1.0.0) with new trifast CUDA attention and new diffusion steering potentials. Added steering option (default false). Using RBVI Boltz 1.0.0 fork with bfloat16 option and trifast fix.
• May 12, 2025. Added 16-bit floating point option to predict larger structures. Using RBVI Boltz 0.4.1 fork.
• April 23, 2025. Initial Boltz prediction tool using Boltz 0.4.1 from PyPi.