Structural biology / Drug discovery

Boltz-2 Installation and Usage Tutorial

Many introductions to Boltz-2 repeat the paper's claim that it approaches FEP accuracy without an independent test. This page covers installation, input files and output fields, then tests Boltz-2 on public experimental data: 21 PTP1B inhibitors from one congeneric series, compared with AutoDock Vina and with simple size baselines.

Data on this page come from one complete run on Scientify: an A10G GPU rented for about 58 minutes, Boltz-2 and Vina on 21 complexes, 1 hour 13 minutes in total, passed independent review. See the run record

Short answer

Boltz-2 is developed by MIT and Recursion. Its code and weights are released on GitHub (jwohlwend/boltz) under the MIT license and can be used for academic and commercial work. Install it with pip install boltz[cuda] -U; the current PyPI version is 2.2.1 and needs Python 3.10–3.12. The input is a YAML file with the protein sequence, ligand SMILES and an affinity property. boltz predict returns the complex structure, confidence scores and two affinity fields. affinity_pred_value is log10(IC50/μM), lower is stronger, and is meant for comparing active molecules in one series. affinity_probability_binary is a 0–1 binding probability for separating binders from decoys. On 21 PTP1B inhibitors, Boltz-2 ranked compounds clearly better than Vina, but not significantly better than ranking by molecular weight.

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.

Install and check the GPUbash
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
ItemMeasured
GPUNVIDIA A10G 24 GB (AWS g5.2xlarge, 8 CPU cores, 32 GB RAM)
Softwareboltz 2.2.1, Python 3.12, PyTorch 2.14
Peak GPU memory4,429 MiB (sampled every 0.5 s)
Peak RAMAbout 8.4 GiB per command
Time per complexMean 114 s, range 110–133 s (1 structure sample + 5 affinity samples)
Install time252 s (reusing PyTorch from the image)
All 21 complexes succeeded. Memory and time depend on protein length, MSA depth and sample count; measure again for a new system.

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.

ptp1b_lig_23486.yaml (used in this run, sequence truncated)yaml
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: B

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

Command used in this runbash
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
ParameterValue herePurpose
--diffusion_samples1 (default 1)Number of structure samples; the docs cite 25 samples and 10 recycles as AlphaFold 3 defaults
--recycling_steps3 (default 3)Recycling iterations; more is slower
--sampling_steps200 (default 200)Diffusion sampling steps
--diffusion_samples_affinity5Samples for the affinity module
--subsample_msa / --num_subsampled_msaon / 512Use part of the MSA to reduce memory
--no_kernelsonDisable cuEquivariance kernels; use when kernels are unavailable or fail
--use_potentialsnot usedInference-time potentials to improve physical plausibility
--affinity_mw_correctionnot usedMolecular-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 Å.

FieldMeaningUse
affinity_pred_valuelog10(IC50/μM), lower is strongerRanking active analogs; pIC50 = 6 − value
affinity_probability_binaryBinding probability, 0–1Separating binders from non-binders
confidence_scoreOverall confidence, 0–1Whether the structure is reliable
iptm / ligand_iptmInterface confidence, 0–1Whether the ligand placement is reliable; not affinity
complex_plddtLocal structure confidence, 0–1Whether local geometry is reliable
For Ki data, pKi = 6 − log10(Ki/μM). IC50 depends on substrate concentration and assay conditions; rankings can be compared, but numeric differences are not pure prediction errors.

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.

MethodPearsonSpearmanKendall τTop-3 hits
Boltz-20.835 [0.668, 0.931]0.725 [0.373, 0.923]0.587 [0.299, 0.823]3/3
AutoDock Vina0.449 [0.027, 0.789]0.447 [−0.039, 0.776]0.317 [−0.040, 0.618]2/3
Molecular weight0.751 [0.518, 0.898]0.684 [0.304, 0.893]0.525 [0.232, 0.759]2/3
Heavy-atom count0.741 [0.383, 0.929]0.662 [0.271, 0.902]0.539 [0.223, 0.793]3/3
n = 21; brackets are 95% intervals from 20,000 bootstrap resamples over compounds, seed 20261103. Top-3 hits counts how many of the 3 most potent compounds appear in the predicted top 3.
Boltz-2 pIC50-equivalent predictions against experimental pKi; compounds above pKi 8 are predicted near 7.5
Boltz-2 predictions against experimental pKi, Spearman 0.72. The dotted line is y = x; the three most potent compounds are all predicted near 7.5.
Molecular weight against experimental pKi
Ranking by molecular weight alone gives Spearman 0.68, not significantly different from Boltz-2.

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.

PDBBoltz-2 RMSDVina RMSD
2QBP0.49 Å0.76 Å
2QBR5.34 Å4.87 Å
2QBS0.55 Å4.45 Å
Below 2 Å2/31/3
Crystal ligands overlaid with Boltz-2 and Vina predictions in three PTP1B co-crystal structures
Ligand positions after pocket superposition. Dashed is the crystal ligand, blue is Boltz-2, orange is Vina; numbers below give crystal and predicted distances for key polar contacts.

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.

ItemBoltz-2AlphaFold 3
Code licenseMITApache 2.0
Model weightsMIT, public downloadObtained from Google under terms of use
Affinity outputYesNo
Online useNVIDIA NIM and third-party sitesAlphaFold Server (non-commercial)
Local usepip installObtain parameters from Google and deploy per the docs
Compiled from both GitHub repositories, 2026-11-03.

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.

Scientify workspace showing the completed plan and deliverables of the Boltz-2 affinity evaluation
Task completed: plan 5/5, GPU released, report, results table and reproduction package delivered. Interface in Chinese.

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

FAQ

Where is the official Boltz-2 site?

Code, weights, installation instructions and docs are in the GitHub repository jwohlwend/boltz. boltz.com is the developers' company website.

Is Boltz-2 free? Can it be used commercially?

Yes. Code and weights are released under the MIT license, and the developers state they can be used for academic and commercial purposes.

How much GPU memory does Boltz-2 need?

It depends on protein length, MSA depth and sample count. Here a 299-residue protein with one small molecule peaked at about 4.4 GiB on an A10G (MSA subsampled to 512, cuEquivariance kernels off). Measure larger systems yourself.

How do I read affinity_pred_value?

It is log10(IC50/μM); lower is stronger. pIC50 = 6 − affinity_pred_value, so −1.55 corresponds to pIC50 7.55. The developers recommend using it only to compare active molecules in one series.

How accurate is Boltz-2 affinity prediction?

On 21 PTP1B inhibitors here, Pearson was 0.835, clearly better than Vina's 0.449 but not significantly better than the molecular-weight baseline of 0.751, and the most potent compound ranked second. The paper reports a mean Pearson of 0.62 on an FEP+ benchmark subset, versus 0.72 for FEP+. Results vary widely by target, so test on known data before relying on it.

What is the difference between Boltz-2 and AlphaFold 3?

Both predict protein–ligand complex structures. Boltz-2 code and weights are MIT-licensed and it outputs affinity; AlphaFold 3 parameters come from Google under terms of use and it outputs no affinity.

Can I use Boltz-2 online?

Yes, through NVIDIA NIM (build.nvidia.com) and some third-party sites. For batch runs or full control over parameters, run it locally or on a rented GPU.

Can Boltz-2 predict protein–protein binding affinity?

No. The docs state the affinity module only supports small molecules binding to proteins. For protein–protein complexes, interface confidence such as iptm helps judge the structure but does not measure binding strength.

Hand your Boltz-2 calculations to Scientify

Describe the target and compounds. Scientify prepares inputs, rents a GPU when needed, runs Boltz-2 with a docking comparison, analyzes the results, and delivers structure files, a report and code.