> This page is for DiffDock, version 2.3.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 2.3.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/diffdock/2.3.0/llms.txt
> - 2.2.0: https://docs.nvidia.com/nim/bionemo/diffdock/2.2.0/llms.txt
> - 2.1.0: https://docs.nvidia.com/nim/bionemo/diffdock/2.1.0/llms.txt
> - 2.0.1: https://docs.nvidia.com/nim/bionemo/diffdock/2.0.1/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/bionemo/diffdock/1.2.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.
# Getting Started
## Prerequisites
For detailed hardware requirements, supported GPU configurations, and system setup instructions (Docker, NVIDIA Drivers, Container Toolkit), refer to the [Support Matrix](/nim/bionemo/diffdock/support-matrix).
### NGC Account
1. [Create an account on NGC](https://catalog.ngc.nvidia.com/)
2. [Generate an API Key](https://org.ngc.nvidia.com/setup/api-key)
3. Log in to Docker with your NGC API key using `docker login nvcr.io --username='$oauthtoken' --password=`
### NGC CLI Tool
1. Download the [NGC CLI tool](https://org.ngc.nvidia.com/setup/installers/cli) for your OS.
Use NGC CLI version `3.41.1` or newer. Here is the command to install this on AMD64 Linux in your home directory:
```bash
wget --content-disposition https://api.ngc.nvidia.com/v2/resources/nvidia/ngc-apps/ngc_cli/versions/3.41.3/files/ngccli_linux.zip -O ~/ngccli_linux.zip && \
unzip ~/ngccli_linux.zip -d ~/ngc && \
chmod u+x ~/ngc/ngc-cli/ngc && \
echo "export PATH=\"\$PATH:~/ngc/ngc-cli\"" >> ~/.bash_profile && source ~/.bash_profile
```
2. Set up your NGC CLI tool locally. You will need your API key for this.
```bash
ngc config set
```
After you enter your API key, you might see multiple options for the org and team. Select as desired or press Enter to accept the default.
## Launch the DiffDock NIM
1. Pull the NIM container.
```bash
docker pull nvcr.io/nim/mit/diffdock:2.3.0
```
2. Run the container.
The environment variable `NGC_API_KEY` must be defined and valid in your local environment for the following command to proceed. For information about personal API key setup, refer to the [NGC User Guide](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#generating-personal-api-key).
```bash
export NGC_API_KEY=
```
```bash
docker run --rm -it --name diffdock-nim \
--runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=0 \
--shm-size=2G \
--ulimit memlock=-1 \
--ulimit stack=67108864 \
-e NGC_API_KEY=$NGC_API_KEY \
-p 8000:8000 \
nvcr.io/nim/mit/diffdock:2.3.0
```
3. Open a new terminal and use the following command to check the API status until it returns `true`. This can take a couple of minutes.
```bash
curl localhost:8000/v1/health/ready
```
Example output:
```bash
true
```
## Run Inference
1. Open a new terminal, leaving the current terminal open with the launched service.
2. Prepare the JSON request body. Run this step in bash. Check the shell with `echo $0`. If it is not bash, run `/bin/bash` first.
`sed` converts the multi-line file into one line for JSON encoding.
```bash
protein_bytes=`curl https://files.rcsb.org/download/8G43.pdb | grep -E '^ATOM' | sed -z 's/\n/\\\n/g'`; \
ligand_bytes=`curl https://files.rcsb.org/ligands/download/ZU6_ideal.sdf | sed -z 's/\n/\\\n/g'`; \
echo "{
\"ligand\": \"${ligand_bytes}\",
\"ligand_file_type\": \"sdf\",
\"protein\": \"${protein_bytes}\",
\"num_poses\": 1,
\"time_divisions\": 20,
\"steps\": 18,
\"save_trajectory\": false,
\"is_staged\": false
}" > diffdock.json
```
3. Run inference and save the response to `output.json`.
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data @diffdock.json \
--output output.json \
http://localhost:8000/molecular-docking/diffdock/generate
```
4. The output file `output.json` is JSON with the predicted docking poses. The fields are:
| Field | Type | Description |
|-------|------|-------------|
|status |str | report 'success' or 'fail' for this request |
|details|str | detailed information for success or failure |
|protein|str | protein PDB text from the input |
|ligand |str | ligand molecule description from the input |
|ligand_positions| list of str | list of [SDF](https://chem.libretexts.org/Courses/Intercollegiate_Courses/Cheminformatics/02%3A_Representing_Small_Molecules_on_Computers/2.05%3A_Structural_Data_Files) formatted text as the generated poses |
|position_confidence|list of float| list of confidence scores for the generated poses |
|trajectory | list of str | list of [PDB](https://en.wikipedia.org/wiki/Protein_Data_Bank_(file_format)) formatted text as the diffusion trajectories for the generated poses (optional) |
## Dump Generated Poses
1. Use the Python script in this section to write the docked ligand poses into a folder named `output`. Create a file named `dump_output.py` and copy the content below into it.
```python
import json
import os
import shutil
def dump_one(folder, ligand_positions, position_confidence):
os.makedirs(folder, exist_ok=True)
for i, c in enumerate(position_confidence):
with open('%s/rank%02d_confidence_%0.2f.sdf' % (folder, i+1, c), 'w') as f:
f.write(ligand_positions[i])
shutil.rmtree('output', ignore_errors=True)
os.makedirs('output', exist_ok=True)
with open('output.json') as f:
data = json.load(f)
if type(data['status']) == str:
dump_one('output', data['ligand_positions'], data['position_confidence'])
else:
for i in range(len(data['status'])):
dump_one('output/ligand%d' % (i+1), data['ligand_positions'][i], data['position_confidence'][i])
```
2. Run the command below to launch the Python script.
```bash
python3 dump_output.py
```
3. List the content in the output folder.
```bash
$ ls output
rank01_confidence_-0.98.sdf
```
## Stop the Container
When you are done testing the endpoint, stop the container by running `docker stop diffdock-nim` in a new terminal.