BindCraft, and binder design by backpropagating through AlphaFold2

Select a target, and the script does the rest

BindCraft is a simple binder design pipeline using AlphaFold2 backpropagation, MPNN and PyRosetta, and the pitch is that you select your target and the script does the rest of the work and finishes once you have enough designs to order.

That is the whole model. The three components have distinct jobs. AlphaFold2 provides the structure prediction and, unusually, the gradient signal, because the pipeline backpropagates through the model rather than treating it as a black box that scores a finished sequence. The message passing neural network handles sequence design, proposing amino acids for positions given the backbone. And PyRosetta provides the energy and interface evaluation used to accept or reject a design.

Backpropagating through a structure predictor is the idea that makes the approach different from a generate and filter loop. If the model can be differentiated, the design step can be optimised against the model's own objective rather than sampled blindly and scored afterwards, which is why the pipeline needs GPU memory and why the number of trajectories it runs matters.

The project is a research tool with a preprint on bioRxiv, and the primary language of the repository is Jupyter Notebook, with the main script in Python and a directory of notebooks.

One instruction in the project description is worth repeating before anything else, because it saves a lot of wasted compute. Before posting an issue, read the complete wiki, since issues that are covered in the wiki will be closed without an answer.

Installation: a CUDA card, a package manager and 5.3 GB of weights

The installation is a clone and a shell script, and the requirements are stated without hedging.

git clone https://github.com/martinpacesa/BindCraft [install_folder]

You navigate into the install folder with cd and run the installation code. BindCraft requires a CUDA-compatible Nvidia graphics card to run. In the cuda setting you specify the CUDA version compatible with your graphics card, for example 11.8, and if you are unsure you leave it blank, though the installation might then select the wrong version, which leads to errors. In pkg_manager you specify whether you are using mamba or conda, and if left blank it uses conda by default.

bash install_bindcraft.sh --cuda '12.4' --pkg_manager 'conda'

The storage numbers are given too, and they are worth internalising. The code requires about 2 Mb of storage space, while the AlphaFold2 weights take up about 5.3 Gb. So the code is trivial and the model is not, and the weights are the thing that fills a disk.

There is one licence condition that a commercial lab needs to handle. The install script installs PyRosetta, which requires a license for commercial purposes. PyRosetta requires a license for commercial purposes, and the script pulling it in does not settle the question for you.

The project is MIT licensed, with releases v1.5.3 from 2026-04-17, v1.5.2 from 2025-06-30 and v1.5.1 from 2025-04-06, and the last push was on 2026-09-21.

Three JSON files, and how to run without a cluster

The pipeline is configured through three separate JSON files, and the separation is what makes it usable.

The target file lives in the settings_target folder and describes what you are designing against.

design_path         -> path where to save designs and statistics
binder_name         -> what to prefix your designed binder files with
starting_pdb        -> the path to the PDB of your target protein
chains              -> which chains to target in your protein, rest will be ignored
target_hotspot_residues   -> which position to target for binder design, for example `1,2-10` or chain specific `A1-10,B1-20` or entire chains `A`, set to null if you want AF2 to select binding site; better to select multiple target residues or a small patch to reduce search space for binder
lengths           -> range of binder lengths to design
number_of_final_designs   -> how many designs that pass all filters to aim for, script will stop if this many are reached

The filters file says which designs are rejected, and the advanced file controls the design process itself.

On a Slurm cluster, the run is a single sbatch invocation with three flags.

sbatch ./bindcraft.slurm --settings './settings_target/PDL1.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json'

If you leave out the filters and advanced settings flags it points to the defaults automatically. If your machine does not support Slurm, you can run the code directly by activating the environment in conda and running the Python code.

conda activate BindCraft
cd /path/to/bindcraft/folder/
python -u ./bindcraft.py --settings './settings_target/PDL1.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json'

The defaults are named default_4stage_multimer, and the four stages are the next thing to look at.

Four stages of iteration, and the switches that change them

The advanced settings file is long, and the design iteration block is the part that explains the pipeline's behaviour.

# Design iterations
soft_iterations                 -> number of soft iterations (all amino acids considered at all positions)
temporary_iterations            -> number of temporary iterations (softmax, most probable amino acids considered at all positions)
hard_iterations                 -> number of hard iterations (one hot encoding, single amino acids considered at all positions)
greedy_iterations               -> number of iterations to sample random m

The progression is a gradual sharpening of the sequence distribution. Soft iterations consider every amino acid everywhere, temporary iterations use a softmax so the most probable residues dominate, hard iterations commit to a single residue per position, and the greedy stage samples randomly at the end. That is a standard annealing shape, and it explains why the defaults are named for four stages: each stage is a different freedom for the designer, and the pipeline moves from open to closed.

The other advanced switches are about how much of the target is held fixed. There are switches to remove the target template sequence for design and for reprediction, which increases target flexibility, and switches to remove target template sidechains for design and for reprediction. There is a switch to use AF2-ptm or AF2-multimer for design, with the other model then used for validation, and separate counters for the number of AF2 recycles in design and in validation.

Two of them are described as rescue options. Predicting the initial guess introduces bias by providing binder atom positions as a starting point for prediction, and is recommended if designs fail after MPNN optimisation. Predicting bigbang introduces atom position bias into the structure module for atom initialisation, and is recommended if target and design are large, more than 600 amino acids.

The rest are sampling controls, including a recommendation to sample models randomly to avoid overfitting, and the omit and force reject amino acid settings.

How many designs to make, and what the ranking metric is worth

The project gives unusually concrete guidance on the two questions that decide whether a run is useful, and it is worth taking both literally.

The first is volume. The recommendation is to generate at least 100 final designs passing all filters, then order the top 5 to 20 for experimental characterisation. The number of trajectories behind that is larger: be ready to run at least a few hundred to see some accepted binders, and for difficult targets it might even be a few thousand.

That ratio is the point. Hundreds of trajectories produce a hundred survivors, and the survivors produce a handful worth spending money on. A run that produces five designs has not failed, it has just not been run long enough, and a user who does not know that will conclude the pipeline does not work.

The second is what the ranking metric means. If high affinity binders are required, it is better to screen more, because the ipTM metric used for ranking is not a good predictor for affinity, but has been shown to be a good binary predictor of binding.

That sentence is the most important methodological claim in the documentation. ipTM tells you whether a design binds or does not, with reasonable reliability, and it does not tell you how tightly it binds. So the pipeline can produce a list of plausible binders, and choosing among them by affinity needs something else, which in practice is the experiment.

The other practical advice is about the input rather than the output. Always try to trim the input target PDB to the smallest size possible, because it significantly speeds up binder generation and minimises the GPU memory requirements. A large target with a small binding site is the case where the search space explodes.

Colab for a smoke test, a local GPU for the real thing

The project ships a Colab notebook to test the BindCraft code functionalities, and it recommends against using it for real work.

The reason is memory. The pipeline requires a significant amount of GPU memory to run for larger target and binder complexes, and the recommendation is to run it with a local installation and at least 32 Gb of GPU memory. The Colab notebook is there so you can confirm the code works, not so you can design binders in it.

That split is a good habit in general, and it is worth noting that the Colab notebook lives in the notebooks directory next to the main script, so the same code is exercised in both places. The example directory holds a PDL1.pdb, which is the target used in the settings examples, so a new user can run the documented example rather than inventing a target first.

The repository layout is organised around that workflow. There is bindcraft.py as the main script, bindcraft.slurm as the Slurm entry point, an install_bindcraft.sh, a functions directory for the supporting code, the three settings directories, the notebooks directory, and the example directory.

The settings folders are separated by role rather than by version, which means a lab can keep its own target definitions, its own filter thresholds and its own advanced settings under version control next to the pipeline, and change one without touching the others.

Editorial conclusion

Adopt BindCraft if you are doing de novo protein binder design and want a pipeline that automates the loop of proposing a sequence, predicting its structure, scoring it and filtering it, with the settings split into target, filter and advanced files you can version. Do not adopt it as a replacement for experimental characterisation, since the project is explicit that the ranking metric is a binary predictor of binding rather than a good affinity predictor. Before you run it, check that you have a CUDA capable Nvidia card, trim the target PDB to the smallest useful size, and plan for a few hundred trajectories at least, since accepted binders are rare even for easy targets.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. martinpacesa/BindCraft on GitHub
4. README
5. Releases