> This page is for Boltz-2, version 1.10.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.10.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/boltz2/1.10.0/llms.txt
> - 1.9.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.9.0/llms.txt
> - 1.8.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.8.0/llms.txt
> - 1.7.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.7.0/llms.txt
> - 1.6.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.6.0/llms.txt
> - 1.5.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.5.0/llms.txt
> - 1.4.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.4.0/llms.txt
> - 1.3.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.3.0/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Loading Custom / Fine-Tuned Boltz-2 Checkpoints

The Boltz-2 NIM supports **same-architecture** checkpoint swapping: you can load
your own Boltz-2 weights (for example, weights fine-tuned externally on synthetic
data) instead of the default checkpoints downloaded from NGC. This enables
iterative *fine-tune → re-serve → screen* workflows without changing the model
architecture.

<Note>
Fine-tuning itself is performed outside the NIM. Supply `.ckpt` files that are
weight-compatible with the stock Boltz-2 structure and affinity models.
</Note>

## Resolve Checkpoint Files

At startup the NIM resolves each model file through a single model root:

1. If `MODEL_PATH` is set, files are loaded directly from that directory.
2. Otherwise files are loaded from the NGC cache under `NIM_CACHE_PATH`.

The following filenames are expected in the model root:

| Purpose            | Default filename    | Override env var                |
| ------------------ | ------------------- | ------------------------------- |
| Structure weights  | `boltz2_conf.ckpt`  | `NIM_BOLTZ_CONF_CKPT_FILE`      |
| Affinity weights   | `boltz2_aff.ckpt`   | `NIM_BOLTZ_AFFINITY_CKPT_FILE`  |
| CCD components     | `ccd.pkl`           | None                            |
| Molecule cache     | `mols.tar`          | None                            |

If your checkpoint files use different names, set the corresponding override environment
variable to the filename **inside** the mounted directory (not a full path). `ccd.pkl` and `mols.tar` keep those filenames.

## Start the NIM With Custom Checkpoints

Mount your checkpoint directory, disable the default download, and point
`MODEL_PATH` at the mount:

```bash
# Directory on the host holding your Boltz-2 assets
CUSTOM_MODEL_DIR=/data/boltz2-finetuned
```

```bash
docker run -it \
    --runtime=nvidia \
    --gpus '"device=0"' \
    -p 8000:8000 \
    --shm-size=16G \
    -v "$CUSTOM_MODEL_DIR":/opt/nim/custom-model:ro \
    -e MODEL_PATH=/opt/nim/custom-model \
    -e NIM_DISABLE_MODEL_DOWNLOAD=1 \
    nvcr.io/nim/mit/boltz2:1.10.0
```


Expected layout of `$CUSTOM_MODEL_DIR` (stock filenames):

```
/data/boltz2-finetuned/
├── boltz2_conf.ckpt
├── boltz2_aff.ckpt
├── ccd.pkl
└── mols.tar
```

## Rename Checkpoints

If you keep multiple fine-tuned checkpoints in the same directory and want to
select one by name, override the filename(s):

```bash
docker run -it \
    --runtime=nvidia \
    --gpus '"device=0"' \
    -p 8000:8000 \
    --shm-size=16G \
    -v "$CUSTOM_MODEL_DIR":/opt/nim/custom-model:ro \
    -e MODEL_PATH=/opt/nim/custom-model \
    -e NIM_DISABLE_MODEL_DOWNLOAD=1 \
    -e NIM_BOLTZ_CONF_CKPT_FILE=boltz2_conf_run42.ckpt \
    -e NIM_BOLTZ_AFFINITY_CKPT_FILE=boltz2_aff_run42.ckpt \
    nvcr.io/nim/mit/boltz2:1.10.0
```


With the above, the NIM loads `boltz2_conf_run42.ckpt` /
`boltz2_aff_run42.ckpt` from `MODEL_PATH`; `ccd.pkl` and `mols.tar` are still
read from the same directory with their default names.

## Notes and Limitations

- **Same architecture only.** Weights must match the stock Boltz-2 structure and
  affinity module shapes. Architecture changes are not supported.
- The `ccd.pkl` and `mols.tar` assets must be present in the model root. If you
  are fine-tuning only the weights, copy these from the stock NGC download.
- An empty override value is treated as unset and falls back to the default
  filename.