Boltz

Boltz-2: Biomolecular Structure and Binding Affinity Prediction

Overview

Boltz-2 is a biomolecular foundation model that jointly predicts complex 3D structure and binding affinity in a single inference pass. It is the first fully open-source model to approach AlphaFold 3-level structural accuracy while also providing quantitative affinity predictions 1000× faster than physics-based FEP methods.

Capability	Boltz-2	AlphaFold 3
Proteins, RNA, DNA, ligands	✓	✓
Binding affinity prediction	✓	✗
Pocket/contact constraints	✓	✗
Cyclic peptides	✓	✗
License	MIT (commercial OK)	CC-BY-NC-SA 4.0
Model weights	Freely available	Must apply to Google
Input format	YAML	JSON
Output format	mmCIF or PDB	mmCIF only

Installation

pip install boltz[cuda] -U

For CPU-only (slow, for testing):

pip install boltz -U

Requirements: Python ≥ 3.10, < 3.13; NVIDIA GPU recommended.

Quick Start

# Predict structure (auto-generate MSA via server)
boltz predict input.yaml --use_msa_server

# Predict structure + binding affinity
boltz predict complex.yaml --use_msa_server --diffusion_samples 5

# Multiple samples for ensemble
boltz predict input.yaml --use_msa_server --diffusion_samples 5

Input Format (YAML)

Boltz-2 uses YAML input files. See references/input-format.md for the full schema.

Single protein

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD

Protein–ligand complex

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD
      msa: ./msas/protein_a.a3m
  - ligand:
      id: B
      ccd: ATP
  - ligand:
      id: C
      ccd: MG

With binding affinity prediction

Add a properties block with one small molecule as the binder:

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD
      msa: ./msas/protein_a.a3m
  - ligand:
      id: B
      smiles: "CC(=O)Nc1ccc(O)cc1"
properties:
  - affinity:
      binder: B

With pocket constraint

Guide the ligand to a known binding site:

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD
  - ligand:
      id: B
      smiles: "CC(=O)Nc1ccc(O)cc1"
constraints:
  - pocket:
      binder: B
      contacts:
        - [A, 45]
        - [A, 67]
        - [A, 89]
      max_distance: 6.0

Homomeric complex

version: 1
sequences:
  - protein:
      id: [A, B, C]
      sequence: MKTAYIAKQRQISFVK

Protein–DNA complex

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTAYIAKQRQISFVK
  - dna:
      id: B
      sequence: GACCTCTGAGGT

Running Predictions

# Basic: provide your own MSA files in the YAML
boltz predict input.yaml

# Auto-generate MSA (no local databases needed)
boltz predict input.yaml --use_msa_server

# More samples for better coverage
boltz predict input.yaml --use_msa_server --diffusion_samples 5

# Use inference-time potentials (improves physical quality)
boltz predict input.yaml --use_msa_server --use_potentials

# Batch: predict all YAMLs in a directory
boltz predict ./jobs/ --use_msa_server

# Output PDB instead of mmCIF
boltz predict input.yaml --use_msa_server --output_format pdb

# Rerun from scratch (override cache)
boltz predict input.yaml --use_msa_server --override

Key CLI flags

Flag	Default	Description
--use_msa_server	false	Auto-generate MSA via mmseqs2 API
--use_potentials	false	Apply inference-time potentials
--diffusion_samples	1	Number of structure samples per input
--recycling_steps	3	Structure recycling iterations
--sampling_steps	200	Diffusion sampling steps
--output_format	mmcif	mmcif or pdb
--override	false	Rerun ignoring cached results

Output Format

out_dir/predictions/<job_name>/
├── <job_name>_model_0.cif              ← predicted structure (best sample)
├── confidence_<job_name>_model_0.json  ← confidence metrics
├── affinity_<job_name>.json            ← binding affinity (if requested)
├── pae_<job_name>_model_0.npz          ← PAE matrix
├── pde_<job_name>_model_0.npz          ← predicted distance error
└── plddt_<job_name>_model_0.npz        ← per-residue pLDDT

With --diffusion_samples 5: output files for _model_0 through _model_4.

Confidence metrics

From confidence_<job_name>_model_0.json:

Metric	Range	Interpretation
confidence_score	0–1	Primary: 0.8 × complex_plddt/100 + 0.2 × iptm
iptm	0–1	Interface confidence (>0.6 = acceptable, >0.8 = high)
ptm	0–1	Global fold confidence
complex_plddt	0–100	Mean per-residue local confidence
complex_iplddt	0–100	pLDDT at protein-ligand interface
complex_pde	Å	Predicted Distance Error (lower = better)

Affinity output

From affinity_<job_name>.json:

{
  "affinity_probability_binary": 0.85,
  "affinity_pred_value": -2.1
}

Field	Use for	Interpretation
affinity_probability_binary	Hit screening (binder vs. non-binder)	0–1; >0.5 = predicted binder
affinity_pred_value	Lead optimization (ranking actives)	log₁₀(IC₅₀ in μM); lower = stronger

affinity_pred_value scale:

• −3 → IC₅₀ = 1 nM (very potent)
• 0 → IC₅₀ = 1 μM
• 3 → IC₅₀ = 1 mM (very weak)

Convert to kcal/mol: ΔG ≈ (6 − y) × 1.364

Important: Use affinity_probability_binary for screening (distinguish binders from non-binders). Use affinity_pred_value only when comparing active compounds — do not use it to compare actives against inactives.

When to Use Boltz-2 vs AlphaFold 3

Use Boltz-2 when:

• You need binding affinity estimates alongside structure
• Commercial use is required (MIT license vs AF3's non-commercial restriction)
• You want pocket constraints to guide ligand placement
• You are working with cyclic peptides
• You need fast iterative screening

Use AlphaFold 3 when:

• You have access to model weights and purely academic use is fine
• You need post-translational modifications (Boltz-2 supports them via CCD but more limited)
• Reproducing AF3 benchmark results is required

Scripts

# Build a YAML input from sequences and ligands
python scripts/build_input.py --name my_job \
  --protein MKTAYIAKQRQISFVK \
  --ligand-smiles "CC(=O)Nc1ccc(O)cc1" \
  --affinity B

# Build from a FASTA file
python scripts/build_input.py --name complex \
  --from-fasta sequences.fasta \
  --ligand-ccd ATP

# Parse and summarize an output directory
python scripts/build_input.py --report predictions/my_job/

Resources

• GitHub: https://github.com/jwohlwend/boltz
• Boltz-2 paper: Passaro et al., bioRxiv 2025 — https://doi.org/10.1101/2025.06.14.659707
• Boltz-1 paper: Wohlwend et al., bioRxiv 2024 — https://doi.org/10.1101/2024.11.19.624167

References

• references/input-format.md — full YAML schema: all entity types, constraints (pocket, bond, contact), affinity properties, modifications, templates, MSA options
• references/outputs.md — parsing mmCIF, confidence JSON, affinity JSON, PAE/pLDDT arrays; batch ranking