About this page
Tutorial- What this page solves
- You want to predict protein–ligand complex structures and binding affinity with Boltz-2 but are unsure how to install it, how much GPU memory it needs, how to write the YAML, how to read the outputs, and how far to trust them.
- Who it is for
- Graduate students in medicinal chemistry, computational chemistry or structural biology who use the Linux command line and Python.
- What you will have
- You will be able to run Boltz-2 on your own GPU, interpret its affinity output correctly, and know how it performed and where it fell short in a congeneric ranking test.
- Covers
- Installation, license and measured GPU memory
- YAML input with affinity and MSA
- The command and parameters used in a real run
- Output files, confidence fields and affinity fields, with unit conversion
- Ranking test on 21 compounds: Boltz-2, Vina, molecular weight and heavy-atom count
- Ligand RMSD against 3 co-crystal structures
- Does not cover
- Protein–protein affinity (not supported by Boltz-2)
- FEP free-energy calculations
- Using AlphaFold 3 (see the AlphaFold 3 guide)
Main steps
Step 1
Why this stepCheck the version, license and hardware before you discover memory or dependency problems.
Boltz-2 code and weights are published in the GitHub repository jwohlwend/boltz under the MIT license, free for academic and commercial use. boltz.com is the website of the company founded by the developers and offers separate commercial products. Without a local install, NVIDIA NIM (build.nvidia.com) and some third-party sites run Boltz-2 online.
Install with pip install boltz[cuda] -U. The current PyPI version is 2.2.1 (2025-09-08) and requires Python 3.10 to 3.12. Without an NVIDIA GPU, drop [cuda]; the official README notes that the CPU version is significantly slower. Use a separate virtual environment and record the package and weight versions.
Some tutorials state that Boltz-2 needs at least 24 GB of GPU memory. In our run on an A10G (24 GB), a 299-residue protein with ligands of 21 to 37 heavy atoms peaked at about 4.4 GiB, at 110 to 133 seconds per complex. This used MSA subsampling to 512 sequences with cuEquivariance kernels disabled; longer proteins or deeper MSAs need more memory.
python -m venv .boltz-env && source .boltz-env/bin/activate
pip install boltz[cuda] -U
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
boltz predict --help | head| Item | Measured |
|---|---|
| GPU | NVIDIA A10G 24 GB (AWS g5.2xlarge, 8 CPU cores, 32 GB RAM) |
| Software | boltz 2.2.1, Python 3.12, PyTorch 2.14 |
| Peak GPU memory | 4,429 MiB (sampled every 0.5 s) |
| Peak RAM | About 8.4 GiB per command |
| Time per complex | Mean 114 s, range 110–133 s (1 structure sample + 5 affinity samples) |
| Install time | 252 s (reusing PyTorch from the image) |
Step 2
Why this stepBoltz-2 outputs affinity only when the YAML contains the affinity property.
Each chain is one entry in the YAML: a protein with an id and amino-acid sequence, a ligand with an id and SMILES. Under properties, affinity uses binder to name the ligand chain whose affinity is computed. Protein and ligand ids must differ.
The official documentation sets these limits: affinity is computed for only one small molecule at a time; it must be a ligand chain, not protein, DNA or RNA; the ligand can have at most 128 atoms (counting hydrogens kept by RDKit), and ligands much larger than 56 atoms are not recommended. Boltz-2 only supports small-molecule–protein affinity and cannot predict protein–protein binding strength.
The MSA is a multiple sequence alignment of the protein that provides evolutionary information. --use_msa_server sends the protein sequence to an MMseqs2 service to build the MSA; you can also put an existing a3m file path in the msa field. For a series of ligands on one protein, build the MSA once and reuse it to save time and keep inputs identical. The MSA here had 10,612 sequences.
version: 1
sequences:
- protein:
id: A
sequence: MEMEKEFEQIDKSGSWAAIYQDIRHEASDFPCRVAKLP...
msa: inputs/msa/protein.a3m
- ligand:
id: B
smiles: 'O=C([O-])COc1c(C(=O)[O-])sc(-c2cccc(NC3CCN(S(=O)(=O)Cc4ccccc4)CC3)c2)c1Cl'
properties:
- affinity:
binder: BStep 3
Why this stepParameters set how many structures are sampled, how many affinity samples are taken, and how much memory is used.
The simplest command is boltz predict input.yaml --use_msa_server. The input can be one YAML file or a folder of YAML files processed in turn.
Below are the full parameters used for all 21 ligands: 1 structure sample, 5 affinity samples, the same settings and seed for every ligand, and no crystal template or pocket constraint. To reduce memory, MSA subsampling and --no_kernels were added, which differs from the official defaults.
Exit code 0 does not mean success. The official program can catch an inference error and still exit normally, so check after each run that the structure file, confidence JSON and affinity JSON all exist.
boltz predict inputs/boltz/lig_23486.yaml --out_dir structures/boltz \
--model boltz2 --devices 1 --accelerator gpu --seed 20261103 \
--recycling_steps 3 --sampling_steps 200 --diffusion_samples 1 \
--max_parallel_samples 1 --step_scale 1.5 \
--sampling_steps_affinity 200 --diffusion_samples_affinity 5 \
--max_msa_seqs 8192 --subsample_msa --num_subsampled_msa 512 \
--output_format mmcif --write_full_pae --write_full_pde --no_kernels| Parameter | Value here | Purpose |
|---|---|---|
| --diffusion_samples | 1 (default 1) | Number of structure samples; the docs cite 25 samples and 10 recycles as AlphaFold 3 defaults |
| --recycling_steps | 3 (default 3) | Recycling iterations; more is slower |
| --sampling_steps | 200 (default 200) | Diffusion sampling steps |
| --diffusion_samples_affinity | 5 | Samples for the affinity module |
| --subsample_msa / --num_subsampled_msa | on / 512 | Use part of the MSA to reduce memory |
| --no_kernels | on | Disable cuEquivariance kernels; use when kernels are unavailable or fail |
| --use_potentials | not used | Inference-time potentials to improve physical plausibility |
| --affinity_mw_correction | not used | Molecular-weight correction on the affinity value |
Step 4
Why this stepThe two affinity fields have different uses, and confidence scores are not binding strength.
Each input gets a folder under predictions/<input name>/ containing the structure <input name>_model_0.cif, the confidence file confidence_<input name>_model_0.json, the affinity file affinity_<input name>.json, and pae, pde and plddt npz files.
affinity_pred_value is log10(IC50) with IC50 in μM; lower means stronger binding. The docs say it is for comparing active molecules in one series, such as hit-to-lead and lead optimization, not for judging inactives. Convert to pIC50 with 6 − affinity_pred_value; for example, −1.55 corresponds to pIC50 7.55, about 28 nM.
affinity_probability_binary is a probability from 0 to 1 for separating binders from decoys, suited to hit discovery. It is neither a Kd nor the probability of measured activity.
confidence_score, iptm, ligand_iptm and complex_plddt measure how confident the model is about geometry; higher is more reliable, but they do not indicate binding strength. In this run, the 2QBR prediction had ligand_iptm 0.96 and still a ligand RMSD of 5.34 Å.
| Field | Meaning | Use |
|---|---|---|
| affinity_pred_value | log10(IC50/μM), lower is stronger | Ranking active analogs; pIC50 = 6 − value |
| affinity_probability_binary | Binding probability, 0–1 | Separating binders from non-binders |
| confidence_score | Overall confidence, 0–1 | Whether the structure is reliable |
| iptm / ligand_iptm | Interface confidence, 0–1 | Whether the ligand placement is reliable; not affinity |
| complex_plddt | Local structure confidence, 0–1 | Whether local geometry is reliable |
Concepts and judgment
Test results
Why this stepTest Boltz-2's ranking ability for lead optimization on public experimental data.
Data come from the PTP1B target in the Open Force Field protein-ligand-benchmark. Of the 22 ligands, one did not match its ChEMBL structure and was excluded before prediction, leaving 21 with Ki values spanning pKi 5.4 to 9.2. Vina used the 2QBS crystal receptor and a fixed docking box with the same protocol for every ligand. Molecular weight and heavy-atom count served as baselines, the simplest possible ranking: larger molecules bind more strongly.
Boltz-2 reached Pearson 0.835 and Vina 0.449. In 20,000 paired bootstrap resamples over compounds, the 95% intervals for Boltz-2 minus Vina were above zero for all three correlation coefficients, so Boltz-2 ranked this series clearly better than Vina.
The molecular-weight baseline, however, reached Pearson 0.751. The intervals for Boltz-2 minus molecular weight all crossed zero, so Boltz-2 did not significantly beat ranking by size. In this series the more potent compounds are mostly larger, and size alone recovers most of the ranking.
The most potent compound, lig_23486 (Ki 0.68 nM), was ranked second by Boltz-2. The three compounds with experimental pKi above 8 were all predicted around 7.5, so the strongest binder's potency was underestimated. All of the experimental top 3 were in Boltz-2's top 3, so it can narrow a candidate list but should not alone decide synthesis order.
| Method | Pearson | Spearman | Kendall τ | Top-3 hits |
|---|---|---|---|---|
| Boltz-2 | 0.835 [0.668, 0.931] | 0.725 [0.373, 0.923] | 0.587 [0.299, 0.823] | 3/3 |
| AutoDock Vina | 0.449 [0.027, 0.789] | 0.447 [−0.039, 0.776] | 0.317 [−0.040, 0.618] | 2/3 |
| Molecular weight | 0.751 [0.518, 0.898] | 0.684 [0.304, 0.893] | 0.525 [0.232, 0.759] | 2/3 |
| Heavy-atom count | 0.741 [0.383, 0.929] | 0.662 [0.271, 0.902] | 0.539 [0.223, 0.793] | 3/3 |


Test results
Why this stepCheck whether predicted ligand position and orientation match the crystal structures.
RMSD was computed by superposing the predicted protein onto the crystal protein using backbone atoms of pocket residues within 8 Å of the crystal ligand, applying the same transform to the predicted ligand, and then computing symmetry-aware heavy-atom RMSD. Fitting the predicted ligand directly onto the crystal ligand hides position and orientation errors and gives values that are too small.
Of the 3 co-crystal structures, Boltz-2 had 2 below 2 Å (0.49 Å and 0.55 Å) and Vina had 1 (0.76 Å). Both failed on 2QBR: Boltz-2 at 5.34 Å and Vina at 4.87 Å. Three structures cannot show that Boltz-2 is generally more accurate.
These 3 crystal structures were released in 2008, before Boltz-2's structural training cutoff of 2023-06-01, and may be in its training data. The result therefore reflects reproduction of historical public systems rather than prediction on a new target.
| PDB | Boltz-2 RMSD | Vina RMSD |
|---|---|---|
| 2QBP | 0.49 Å | 0.76 Å |
| 2QBR | 5.34 Å | 4.87 Å |
| 2QBS | 0.55 Å | 4.45 Å |
| Below 2 Å | 2/3 | 1/3 |

Choose by your situation
Choices
Why this stepBoth predict protein–ligand complexes; they differ in licensing and affinity output.
AlphaFold 3 source code is released under Apache 2.0, and its model parameters may only be used if received directly from Google, under its terms of use; non-commercial users can also predict online with AlphaFold Server. Boltz-2 code and weights are both MIT-licensed and can be used commercially.
AlphaFold 3 outputs structures and confidence but no binding affinity. To rank a set of compounds, Boltz-2 gives an affinity value directly. For complex structures alone, either works, and AlphaFold Server needs no GPU of your own.
| Item | Boltz-2 | AlphaFold 3 |
|---|---|---|
| Code license | MIT | Apache 2.0 |
| Model weights | MIT, public download | Obtained from Google under terms of use |
| Affinity output | Yes | No |
| Online use | NVIDIA NIM and third-party sites | AlphaFold Server (non-commercial) |
| Local use | pip install | Obtain parameters from Google and deploy per the docs |
Reference and appendix
Run record
Why this stepData source, compute resources and independent review.
The numbers come from a long-running research task on Scientify on 3 November 2026. After the user uploaded a brief, Scientify chose the PTP1B target and checked the experimental data, rented an A10G GPU, installed Boltz-2, ran one complex to confirm the workflow, then completed Boltz-2 predictions and Vina docking for 21 complexes, copied back and verified all results, and released the GPU. GPU use was about 58 minutes; the whole task took 1 hour 13 minutes.
A TensorBoard and protobuf version conflict made the first sample fail; pinning TensorBoard fixed it. Independent review found that the pose evaluation script silently accepted missing pocket atoms; after the fix, the review passed. Deliverables were a 14-page report in Chinese, a results workbook, 8 figures, all predicted structures and docked poses, inputs, code and a reproduction package.

Troubleshooting
The first sample fails with a protobuf VersionError
Cause: A preinstalled TensorBoard requires a newer protobuf than the one Boltz depends on.
Fix: Install Boltz in its own virtual environment and pin a compatible TensorBoard (2.18.0 here). This is an environment issue and does not affect model results.
A structure file exists but no affinity JSON
Cause: The YAML lacks properties and affinity, or binder does not name the ligand chain.
Fix: Check that properties → affinity → binder equals the ligand id and that the boltz2 model is used.
The command finishes normally but output files are missing
Cause: An inference error was caught and the program still returned 0.
Fix: After each run, check for the cif, confidence and affinity files and read the log if any is missing.
CUDA out of memory
Cause: Long protein, deep MSA or too many parallel samples.
Fix: Set --max_parallel_samples 1 and add --subsample_msa; add --no_kernels if kernels fail. These change the calculation, so report them in your methods.
--use_msa_server times out or fails
Cause: The MMseqs2 service is unavailable or the network is restricted.
Fix: Save the error and retry later, or build an a3m locally and put it in the msa field. Build it once per protein and reuse it.
Sources
- Boltz GitHub repository — License, installation and affinity field definitions
- Boltz prediction docs (prediction.md) — YAML format, affinity limits and parameters
- boltz on PyPI — Version 2.2.1, Python 3.10–3.12
- Passaro et al., Boltz-2, bioRxiv 2025
- Open Force Field protein-ligand-benchmark
- Original PTP1B inhibitor paper, J Med Chem 2007
- AlphaFold 3 GitHub repository