Get Started
Linux + NVIDIA GPU, ~30 minutes from clone to first trajectory. If you already have a working stock BindCraft, jump straight to "Updating from stock BindCraft" — the cyclic patch is ~250 lines.
Requirements
GPU: NVIDIA ≥16 GB VRAM minimum, ≥24 GB recommended (A100, A6000, RTX 4090, H100).
CPU: 8 cores min, 16+ recommended (PyRosetta FastRelax is multi-threaded).
RAM: 32 GB min, 64 GB recommended.
Disk: 50 GB free (AF2 params ~5.3 GB + 10 GB PDBs per 200-design run).
Linux (Ubuntu 22.04+): primary, recommended.
macOS (Apple Silicon): experimental — install with pip install jax-metal, expect ~5–10× slower.
Windows + WSL2: supported via WSL2 + Ubuntu 22.04 (PyRosetta wheels are Linux-only).
Native Windows: not supported.
CUDA 11.8 or 12.1 (12.1 recommended).
Python 3.10 (do not use 3.11+ — colabdesign not validated there).
JAX/jaxlib >=0.4, <=0.6.0 with the CUDA-matched wheel.
PyRosetta quarterly release — free for academic/non-commercial use, register at els2.comotion.uw.edu.
CPU-only is impractical
AF2 hallucination requires JAX/GPU backprop through the structure module. On a 32-core CPU a single trajectory takes ~6 hours vs. ~3 minutes on an A100. Cyclic BindCraft will refuse to start if check_jax_gpu() fails (the same behavior as stock BindCraft).
Step-by-step
Seven steps from clone to verified install. Total time ~30 minutes on a fast connection.
mkdir -p ~/cyclic-bindcraft && cd ~/cyclic-bindcraft
git clone https://github.com/martinpacesa/BindCraft.git repo
cd repo
git checkout v1.5.3 # pin to the version Cyclic BindCraft is built against
# Apply the cyclic patch (shipped alongside these docs)
git apply /path/to/cyclic.patch
# or, equivalently, copy the modified-code/ tree over the repo:
# cp -r /path/to/modified-code/functions/cyclic_utils.py functions/
# cp -r /path/to/modified-code/functions/colabdesign_utils.py functions/
# cp -r /path/to/modified-code/functions/pyrosetta_utils.py functions/
# cp -r /path/to/modified-code/functions/biopython_utils.py functions/
# cp -r /path/to/modified-code/functions/generic_utils.py functions/
# cp -r /path/to/modified-code/settings_advanced/peptide_cyclic_3stage.json settings_advanced/
# cp -r /path/to/modified-code/settings_filters/peptide_cyclic_filters.json settings_filters/BindCraft ships install_bindcraft.sh which creates the env, installs conda packages, ColabDesign, and PyRosetta, then downloads AF2 params. Run it with the CUDA version that matches your driver:
cd ~/cyclic-bindcraft/repo
bash install_bindcraft.sh --pkg_manager mamba --cuda 12.1The script takes ~30 minutes on a fast connection. It will:
conda env BindCraft python=3.10pip install git+https://github.com/sokrypton/ColabDesign.git --no-depspip install pyrosetta --find-links https://west.rosettacommons.org/pyrosetta/quarterly/release.cxx11thread.serialization (requires that your PyRosetta license is already registered)alphafold_params_2022-12-06.tar into ./params/chmod +x functions/dssp functions/DAlphaBall.gccconda activate bindcraft # or `mamba activate bindcraft`install_bindcraft.sh already does this. If you skipped that step or want a shared location:
mkdir -p ~/af2_params
wget -O ~/af2_params/alphafold_params_2022-12-06.tar \
https://storage.googleapis.com/alphafold/alphafold_params_2022-12-06.tar
tar -xvf ~/af2_params/alphafold_params_2022-12-06.tar -C ~/af2_params/Then set af_params_dir in your advanced-settings JSON to ~/af2_params/.
ProteinMPNN weights (v_48_020 and the soluble variant) are bundled with ColabDesign — no separate download needed. Verify:
python -c "from colabdesign.mpnn import mk_mpnn_model; m = mk_mpnn_model(weights='soluble'); print('MPNN OK')"python -c "from functions.cyclic_utils import cyclize_relpos, cyclic_bonded_edges, build_cyclic_reses_mask; print('OK')"
python -c "import jax; print('JAX', jax.__version__, 'devices', jax.devices())"
python -c "import pyrosetta; pyrosetta.init('-ignore_unrecognized_res -mute all'); print('PyRosetta OK')"You should see OK, a JAX version 0.4.x–0.6.x, a list that includes a CUDADevice (not just CpuDevice), and PyRosetta OK.
python bindcraft.py \
--cyclic \
--settings settings_target/PDL1.json \
--filters settings_filters/peptide_cyclic_filters.json \
--advanced settings_advanced/peptide_cyclic_3stage.jsonThe first trajectory should appear in Trajectory/ within ~5 minutes on an A100.
Optional
Cyclic BindCraft's primary structure predictor is AF2 with the cyclic relpos applied — this is sufficient for ranking but is still an approximation of a true cyclic-prediction network. For maximum fidelity (especially for designs you intend to synthesize), install one of:
Modified AlphaFold2 with the same cyclic relpos we use, but trained for prediction rather than hallucination. Install:
pip install git+https://github.com/bhardwajlab/AfCycDesign.gitRe-predict your top 5–10 designs and confirm iPAE < 0.13 and RMSD < 1.5 Å vs. the BindCraft output.
RoseTTAFold2 with the cyclic offset. The rfpeptides branch of RosettaCommons/RFdiffusion includes a downstream RF2-cyclic validator. Use it as an orthogonal predictor: if both AfCycDesign and RF2-cyclic agree your design is well-folded, you have high confidence.
Both are optional. They add ~3 GB of weights each and require a second GPU pass per design. See Tutorial step 8.
Troubleshooting
| # | Error | Cause | Fix |
|---|---|---|---|
| 1 | RuntimeError: jaxlib requires CUDA ... but found CUDA ... | JAX wheel CUDA version mismatches driver | Reinstall: pip install --force-reinstall jaxlib==0.4.30+cuda11.8 -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html (match to your driver) |
| 2 | check_jax_gpu() exited: No GPU devices found | JAX configured for CPU only | export XLA_FLAGS=--xla_gpu_cuda_data_dir=/usr/local/cuda and confirm nvidia-smi shows the GPU |
| 3 | pyrosetta.init() raises LicenseError | PyRosetta can't reach the license server | Check your institution's PyRosetta registration; if behind a proxy, export PYROSETTA_LICENSE_SERVER=... |
| 4 | ModuleNotFoundError: No module named 'colabdesign' | ColabDesign not installed in the active env | pip install git+https://github.com/sokrypton/ColabDesign.git --no-deps inside the bindcraft env |
| 5 | FileNotFoundError: params_model_5_ptm.npz | AF2 weights not extracted | Re-run the AF2 download step (step 4 above); set af_params_dir in your settings JSON |
| 6 | OSError: Unable to open file .../functions/dssp | DSSP binary not executable | chmod +x functions/dssp functions/DAlphaBall.gcc |
| 7 | CUDA out of memory during hallucination | Target too large for VRAM | Lower binder_len range, switch to use_multimer_design: false, or use a 40 GB+ GPU |
| 8 | Chainbreak not closed after FastRelax (cyclic mode) | AF2 hallucination produced a geometry that FastRelax cannot close | Increase weights_cyclic_bond_loss to 1.0–2.0 in the cyclic preset; if persists, lower cyclic_NC_distance filter to 1.5 Å to reject early |
| 9 | cyclic_NC_distance > 5 Å on all accepted designs | Cyclic bond loss weight too low | In peptide_cyclic_3stage.json raise weights_cyclic_bond_loss from default 0.5 to 1.5; if still poor, raise weights_termini_loss to 1.0 |
| 10 | All trajectories terminate as LowConfidence | AF2 hallucination too aggressive | Switch from peptide_cyclic_3stage.json to a softer 4-stage variant; lower weights_pae_intra to 0.2; ensure predict_initial_guess: true |
For runtime questions, also check the stock BindCraft issues page. For cyclization-specific errors (cyclic_NC_distance, cyclic_omega, chainbreak-closure failures), see the FAQ.
Patch only
If you already have a working stock BindCraft install, you only need to:
git apply cyclic.patch) — this adds functions/cyclic_utils.py, modifies 4 functions in functions/*.py, adds the --cyclic CLI flag, and ships peptide_cyclic_3stage.json + peptide_cyclic_filters.json.python -c "from functions.cyclic_utils import cyclize_relpos; print('OK')" to confirm.default_filters.json and default_4stage_multimer.json continue to work for linear designs — nothing is removed, only added.The patch is approximately 250 lines of Python on top of stock BindCraft v1.5.3.
cd ~/cyclic-bindcraft/repo
git fetch && git checkout v1.5.3 # pin to the version the patch is built against
git apply /path/to/cyclic.patch
python -c "from functions.cyclic_utils import cyclize_relpos; print('OK')"