Boltz-2 Python Client

Copyright (c) 2025-2026, NVIDIA CORPORATION. All rights reserved.

Python and command-line interfaces for NVIDIA Boltz-2 NIM: protein, DNA/RNA, ligand and covalent complexes, binding affinity, MSA integration, templates, and multi-endpoint screening.

Version 0.6.0 targets NIM 1.9.0. Releases are validated on TestPyPI before production publication. Select the matching index when installing. See migration and compatibility.

The source archive (.tar.gz) under the release page's Download files includes the current guides, scripts and notebooks. Relative links in this README refer to files in that extracted archive or a matching repository checkout.

Install

Python 3.10 or newer:

# PyPI, after production publication
python -m pip install boltz2-python-client==0.6.0

# TestPyPI release and dependencies from PyPI
python -m pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ boltz2-python-client==0.6.0

# From this checkout or the extracted source archive
python -m pip install -e '.[dev,notebooks]'

Optional extras: notebooks (Jupyter and visualization), sagemaker (boto3), analysis (NumPy and structure conversion), and screening (pandas for CSV and DataFrame helpers). The Python client itself needs no GPU; a running NIM server performs inference.

Quick start

Run against a ready local server. This sequence is an input-format example; confidence scores do not establish a biological interaction.

from pathlib import Path
from boltz2_client import Boltz2SyncClient

client = Boltz2SyncClient(base_url="http://localhost:8000", timeout=600)
result = client.predict_protein_structure(
    sequence="MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
    output_dir=Path("results/protein"),
)
print(result.confidence_scores)

For notebooks and asynchronous programs, use Boltz2Client and await:

from boltz2_client import Boltz2Client, Ligand, Polymer, PredictionRequest

client = Boltz2Client(timeout=600)
request = PredictionRequest(
    polymers=[Polymer(id="A", molecule_type="protein", sequence="MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT")],
    ligands=[Ligand(id="L1", smiles="CC(=O)Oc1ccccc1C(=O)O",
                    predict_affinity=True, output_affinity_embedding=True)],
    diffusion_samples=2,
    max_parallel_samples=1,  # NIM 1.9+: lower peak GPU memory
)
result = await client.predict(request, output_dir="results/complex")
print(result.affinities["L1"].affinity_pic50)
print(result.affinities["L1"].affinity_embedding)

The second example demonstrates request syntax using a short protein fragment and aspirin; it is not a validated binding pair. Use full, appropriate target sequences and assess predictions against experimental evidence.

Endpoints

For hosted inference, supply the key through NVIDIA_API_KEY or NGC_API_KEY in the process environment (or api_key in Python). The default hosted base URL is https://health.api.nvidia.com. Local inference sends no authorization header. Hosted deployments may lag the container release; enable version-specific options only when that endpoint supports them.

SageMaker requires the sagemaker extra and configured AWS credentials/region. See the SageMaker connection example. Use asynchronous clients in Jupyter; the synchronous wrapper uses asyncio.run().

CLI

boltz2 health
boltz2 protein ACDEFGHIKLMNPQRSTVWY --output-dir results/protein
boltz2 protein ACDEFGHIKLMNPQRSTVWY --diffusion-samples 2 --max-parallel-samples 1
boltz2 ligand ACDEFGHIKLMNPQRSTVWY --smiles CC --predict-affinity --output-affinity-embedding
boltz2 advanced --config-file examples/data/nim_1_9_request.json --output-dir results/advanced
boltz2 --endpoint-type nvidia_hosted protein ACDEFGHIKLMNPQRSTVWY
boltz2 --multi-endpoint --base-url http://gpu1:8000,http://gpu2:8000 protein ACDEFGHIKLMNPQRSTVWY

These short sequences/ligands illustrate syntax. boltz2 --help lists all commands, including covalent constraints, YAML, MSA conversion and screening.

Results and matrices

predict() saves every structure as structure_0.cif, structure_1.cif, etc., plus prediction_response.json (complete response), prediction_metadata.json (scores, affinities, embeddings and runtime metrics), and affinities.json when present. Use save_structures=False or CLI --no-save to suppress client output. Use separate output directories for separate predictions to avoid overwriting files.

NIM 1.9 does not return full PAE/PDE matrices in JSON. write_full_pae=True and write_full_pde=True create NPZ files on the server under $NIM_OUTPUT_PATH/prediction_*/pae/ and .../pde/. result.pae and result.pde remain None. Mount the server output directory to retrieve these artifacts. Aggregate complex_pde_scores and complex_ipde_scores remain in the response. See outputs for loading matrices and retaining results.

Deploy a local server

Follow local deployment, including GPU/driver prerequisites, NGC login, cache and output mounts. The pinned image is nvcr.io/nim/mit/boltz2:1.9.0. The deployment script checks GPU access before starting a container:

# Set NGC_API_KEY (or NVIDIA_API_KEY) in the environment first.
export LOCAL_NIM_CACHE="$HOME/.cache/nim"
export LOCAL_NIM_OUTPUT="$HOME/boltz2-output"
bash scripts/start_local_nim.sh

Guides and examples

Start with the protein prediction notebook and example index. Guides:

• Parameters, migration, outputs
• Affinity, covalent complexes
• MSA search, A3M multimer pairing
• YAML subset, async usage
• Multiple endpoints, virtual screening
• Validation and release procedure, changelog

License

MIT. Third-party assets retain their licenses. NVIDIA NIM container and model terms are separate from the Python client license.