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.

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

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:

Affinity output

From affinity_<job_name>.json:

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

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