BoltzGen Install Guide: Run Protein Binder Generation Locally

If you’ve been searching how do I actually run protein binder generation on my own GPU? – this is the install path. BoltzGen, the MIT-released all-atom binder design model, is fully open source under MIT license (MIT Jameel Clinic announcement), but the GitHub README assumes you already know your CUDA story. We’ll fill in the gaps.

The reason to deploy locally rather than use a hosted wrapper (Ariax, Tamarind, Rowan): you control the budget. A single production campaign can easily request tens of thousands of designs, and hosted GPU minutes add up fast. Run it yourself and you trade convenience for cost predictability.

What you’re actually installing

Three models, not one. BoltzGen is a pipeline where BoltzGen (diffusion, structure generation) hands off to BoltzIF (inverse folding) then to Boltz-2 (structure validation + affinity prediction). According to the official README, that means seven discrete steps: design, inverse folding, design folding, folding, affinity, analysis, and filtering.

Every design you generate gets folded multiple times. That’s why the GPU bill is what it is – and why the hardware check below matters before you type a single command.

Hardware reality check

The VRAM floor is higher than it looks. At 30-60 seconds per design for systems with a few hundred amino acids (Rowan benchmark, 2025), it’s difficult to exceed 100 designs per GPU-hour. Pair that with the official GitHub guidance – 5,000-60,000 designs for a real production campaign – and you’re looking at 50-600 GPU-hours per target. A 24 GB card will OOM on anything but small systems.

RAM isn’t specified in the official docs – plan for enough headroom alongside your GPU workload and OS. The A10G at 24 GB is officially listed as undersized; the L40S at 48 GB is the community sweet spot, with A100-80GB for targets that keep triggering OOM (per eliteai community skill registry).

The recommended install (conda + PyPI)

Straight from the official README:

# 1. Create a fresh conda environment with Python 3.12
conda create -n bg python=3.12 -y
conda activate bg

# 2. Install BoltzGen from PyPI
pip install boltzgen

# 3. Verify the CLI is on PATH
boltzgen --help

About half of new users hit the same wall: they open a new terminal, run boltzgen, and get command not found. The env isn’t active. Run conda activate bg first. Model weights for the inverse-folding step auto-download from HuggingFace on first run – a few GB the first time, nothing after that.

Editable install (if you want to modify the code)

git clone https://github.com/HannesStark/boltzgen.git
cd boltzgen
pip install -e .

Docker (locked-down HPC nodes)

docker build -t boltzgen .

mkdir -p workdir cache
docker run --rm --gpus all 
 -v "$(realpath workdir)":/workdir 
 -v "$(realpath cache)":/cache 
 -v "$(realpath example)":/example 
 boltzgen 
 boltzgen run /example/vanilla_protein/1g13prot.yaml 
 --output /workdir/test 
 --protocol protein-anything 
 --num_designs 2

Docker is the safest path on shared clusters where you don’t control the system CUDA version.

First-time configuration: a minimum-viable YAML

BoltzGen needs a design spec in YAML. The shortest sensible one defines a designed protein plus a target chain pulled from a CIF file:

# minimal_binder.yaml
entities:
 - protein:
 id: B
 sequence: 80..140 # design a binder of 80-140 residues
 - file:
 path: target.cif
 include:
 - chain:
 id: A
 binding_types:
 - chain:
 id: A
 binding: 45,67,89 # hotspot residues on target

Before spending GPU minutes, validate it:

boltzgen check minimal_binder.yaml

Residue indexing trap: BoltzGen uses the canonical mmCIF index label_asym_id – not auth_asym_id, the author residue index that PyMOL and most visualization tools display. The README calls this out explicitly. Paste indices from PyMOL and your binder gets designed against the wrong patch of the target. Check indexing in your mmCIF file at molstar.org/viewer by hovering over a residue before writing the YAML.

Verify with a real run

Two designs. That’s enough to confirm the whole pipeline executes end-to-end:

boltzgen run minimal_binder.yaml 
 --output ./test_run 
 --protocol protein-anything 
 --num_designs 2 
 --budget 2

Logs should stream through each step. At 30-60 seconds per design (the documented per-design floor), two designs means roughly 1-2 minutes of active GPU work – though startup and weight loading add overhead on first run. BoltzGen outputs CIF format only; if your downstream tools expect PDB, you’ll need a Biopython MMCIFParser conversion step. The output directory BoltzGen creates will contain your ranked candidates.

Common install errors

• CUDA 12.9 / Blackwell GPU (RTX 50-series) install fails. Turns out the dependency chain pins an older torch: as of mid-2025, jwohlwend/boltz issue #506 documents that torch 2.7.1 only supports CUDA 12.8 or lower. The community fix – install a nightly PyTorch build (cu129 or cu130) and comment out the hard torch>=2.2 pin before reinstalling.
• cuEquivariance kernel error on Blackwell. The cuEquivariance library doesn’t support sm_121 yet (per boltz-blackwell PyPI notes, as of mid-2025). Always pass --no_kernels.
• OOM at the folding step. Drop --num_designs, switch to a larger GPU, or trim the target chain to the binding domain. The A100-80GB is the documented fallback.
• Binder targets the wrong region of the protein. See the residue-indexing trap above – label_asym_id vs auth_asym_id.

Upgrade and uninstall

Standard PyPI upgrade:

conda activate bg
pip install --upgrade boltzgen

Cached model weights live outside the Python env, so upgrading won’t re-download them. To wipe everything:

conda deactivate
conda env remove -n bg
rm -rf ./cache ./workdir # plus your HuggingFace cache if you want it gone

One honest unknown: the project is young – the paper is a November 2025 bioRxiv preprint (Stärk et al., 2025) – and the upgrade path between minor versions hasn’t been stress-tested by a large user base yet. Pin the boltzgen version in your environment file for production campaigns. A breaking dependency update mid-run is a bad day.

FAQ

Can I run BoltzGen on a Mac?

No. The documented install path requires Linux with an NVIDIA CUDA GPU. CPU-only execution is technically possible but impractical at production scale.

Why is the recommended design count so high?

The funnel is steep by design. Say you generate 10,000 candidates – then inverse folding runs, re-folding runs, RMSD filters cut, biophysical filters cut again. You might surface 10-100 binders worth sending to the wet lab. Start with 50 designs and the filters often return nothing – not because the model failed, but because that’s how the math works out. For a smoke test, --num_designs 2 --budget 2 skips the filtering stage entirely and just confirms the pipeline runs.

Is BoltzGen free for commercial use?

Yes, MIT license. That matters – AlphaFold 3 has licensing restrictions that BoltzGen doesn’t.

Next step: Clone the repo, run boltzgen run example/vanilla_protein/1g13prot.yaml --num_designs 2, and time it on your hardware. That number is your campaign-planning multiplier.