DiffDock Batch Guide

Download — DiffDock Batch (Windows, macOS, Linux)

Have you ever run a docking job on DiffDock?
NVIDIA lets you try it for free at build.nvidia.com, but the web page takes one protein and one ligand at a time.
With a few dozen candidate ligands and a handful of proteins, you end up uploading files and saving results hundreds of times.

You could call the API yourself, but then you have to write the script.
When you hit the per-minute limit you have to wait and resend, and someone still has to pull the poses and confidence scores out of the JSON.

DiffDock Batch does that work for you.
Pick all your files at once and press Run. It sends every protein × ligand pair to the API in turn and stores the results in a folder.
It paces itself to the rate limit, and when it is done it gathers every result into a single CSV.

Download and launch

Get the zip from the download page, unzip it, and run the file for your system.

• You need Python 3.9 or later. If it is missing, the launcher opens the Python download page.
  On Windows, be sure to tick “Add python.exe to PATH” during setup.
• On the first run only, it prepares its environment (a virtual environment with the requests and keyring packages). This can take a minute or two.
• You need an NVIDIA API key. Sign up at build.nvidia.com to get a free trial key.

On macOS you may see an “unidentified developer” warning the first time.
Control-click the file → Open → Open.
If that still fails, run chmod +x DiffDock_Mac.command in Terminal.

When it starts, a black console window and your browser open together.
The screen lives in the browser, but the program itself runs on your computer.
To quit, close the console window. Closing it mid-run stops the run too.

How to use it

The program’s screen is in Korean. The button and option names below are English translations, given in the same order as on screen.

The basic steps

1. Enter your API key — save it once and you can skip this next time.
2. Add files — use Choose files… to pick several .pdb / .sdf / .mol2 files, or drop them on the dashed area.
3. Output folder — leave it empty to save to Documents/DiffDock_results.
4. Check the options — the defaults are fine as they are.
5. Check files — see the real number of jobs, the expected disk usage and the minimum run time first.
6. Run — start. Press Stop to halt.

Step 5 is there for a reason.
Ten proteins and a hundred ligands make 1,000 jobs, and on the free API that can take more than a day.
That’s why it shows you the size of the job before you commit to it.

Adding files

It sorts proteins from ligands by extension. .pdb is a protein; .sdf and .mol2 are ligands.

• Adding a file with the same name again replaces the old one.
• An SDF/MOL2 with several molecules is split into one ligand per molecule.
  Each is named originalfile_moleculename; if a molecule has no name or the name repeats, a number is used.
  Compound libraries often come as a single SDF, so this saves you splitting them by hand.
• Each file can be up to 50 MB, with up to 100,000 molecules per file.
• The files you pick disappear from the list when you quit. Your original files are untouched.

Pairing mode

If each protein has its own set of ligands, use prefix match.
Just name the ligand files proteinname_ligandname.
Case does not matter.

DiffDock options

These follow DiffDock’s own defaults. Unless you have a reason, leave them alone.
If steps is larger than time_divisions, it refuses to run and shows an error.

The other checkboxes:

• Save trajectory (off by default) — saves how each pose was formed, as trajectory_rank01.pdb and so on. It is large, so it starts off.
• Use protein ATOM lines only (on by default) — sends only the PDB lines that start with ATOM. This keeps water and bound ligands (HETATM) from muddying the result.
• Skip if result exists (on by default) — does not resend a pair that already has a result with the same options. You need this to resume after a stop.
• Upload large files as assets (off by default) — uploads the files to NVIDIA storage first and sends only a reference. Even with this off, if the server answers “too large” (413), it retries this way automatically.
• Store only position_confidence in JSON (on by default) — turn it off to store the full API response in the JSON. Pose structures are saved separately as SDF, so leaving it on is usually better.

Saving pose structures

Ten poses per pair means 13 files per pair. Ten thousand pairs means 130,000 files.
For large runs, switch to combined file only or don’t save. The file count and disk usage drop sharply.
Either way, the confidence scores still land in the combined CSV.

Progress and stopping

While it runs, the log and result table scroll at the bottom and the status line shows the estimated time left.
That estimate is based on the average time of the last 50 jobs.

Press Stop and it halts on the spot. Results already received stay where they are.
The one job that was waiting on the server ends without a result and is sent again next time.
Press Run again and it skips what is done and picks up the rest.

During a run it keeps the computer from going to sleep (Windows and macOS).
Leaving it overnight only to find it asleep would be a waste.

Good to know

2D ligands give no results

DiffDock needs 3D coordinates for the ligand.
Files whose z coordinates are all zero — saved from ChemDraw, or a 2D SDF from PubChem — get a response from the API, but the result is empty.

So it checks the coordinates when you add a file and marks 2D structures as [2D] in the list.
At run time it skips them without calling the API and records them as skipped_2d in summary.csv.
There is no point spending your rate limit on a request that is bound to come back empty.

To get 3D, use any one of these:

• PubChem — compound page → Download → 3D Conformer → SDF
• RCSB ligands — ..._ideal.sdf (ideal coordinates, 3D)
• Open Babel — obabel input.sdf -O output_3d.sdf --gen3d
• RDKit — AllChem.EmbedMolecule(Chem.AddHs(mol)), then save

If a 3D file still returns nothing, the log says the result is empty.
It may be a molecule DiffDock cannot handle, such as a metal complex or a very large molecule.

API rate limits

The NVIDIA free trial is limited by requests per minute, not by credits.
It is commonly said to be 40 per minute, but this can vary by model and time of day, so check your own limit on your build.nvidia.com account page.

The default of 30 for max API requests per minute leaves headroom below 40.
This count covers not only docking requests but also the status checks that ask whether a job is finished, and asset uploads.
That’s why status checks are made only every 10 seconds.

If it still hits the limit (429), it waits as long as the server says and sends again.
If the server does not say, it waits 30, 60, 90 seconds and so on, up to 5 minutes.

When it stops by itself

In these cases carrying on would be pointless, so it stops right away.

• Authentication error (401/403) — the API key is wrong or expired.
• 10 failures in a row — a problem with your internet connection or the NVIDIA service.
  File problems, such as 2D ligands or empty results, do not count toward this.
• Out of disk space — it also warns at the start if less than 2 GB is free.

In every case, fix the cause and press Run again; it continues from where it left off.
Network errors are not counted as failures straight away: it retries up to five times, waiting from 30 seconds and doubling each time.

Output folder layout

output folder/
├── summary.csv                 summary of every job (opens directly in Excel)
├── run_log.txt                 full run log
├── confidence_summary.csv      combined results
├── results_index.jsonl         record used to build the combined CSV (do not delete)
└── 8G43/                       one folder per protein
    └── 8G43-ZU6_ideal-poses10_td20_st18/
        ├── 8G43-ZU6_ideal-poses10_td20_st18.json
        ├── rank01.sdf …
        ├── all_poses.sdf
        └── confidence.csv

The poses10_td20_st18 at the end of the folder name records the options. Saving the trajectory adds _traj.
Rerunning with different options saves under a different name, so earlier results are never overwritten.
Comparing the same pair under different options is common, so it works this way.

confidence_summary.csv has one row per docking job.
After the protein, ligand and options come confidence_rank01 onward, one column per pose.
Open it in Excel and sort, and you can see at a glance which pairs bind well.

Large runs

It is built to handle thousands of files and hundreds of thousands of jobs.

• The files you pick are kept in a temporary folder (~/.diffdock_batch/staging), not in memory, and deleted when you quit.
• The on-screen result table shows only the latest 300 jobs. Everything is in the CSVs and run_log.txt.

But the time it takes is set by the NVIDIA free API. Jobs go one at a time, so
total time ≈ number of jobs × time per job. At 30 seconds per job, 10,000 jobs take about 3.5 days.

3,000 proteins × 500 ligands = 1.5 million jobs is not realistic on the free API.
At 30 seconds per job that is about 1.4 years; even maxing out 40 per minute, it is at least 26 days.
At that scale, install DiffDock on your lab’s own GPU.

API key security

• The key stays inside the program on your computer; the browser only ever sees the last 4 characters.
• Turn on Save securely on this PC to store it in Windows Credential Manager or the macOS Keychain.
  Only where no keychain is available does it fall back to ~/.diffdock_batch/api_key, readable by you alone.
• If you turn saving off and enter a new key, the previously saved key is deleted. Delete saved key removes it at any time.
• The key is sent only to the NVIDIA API (over HTTPS) and is masked in the log and summary.csv.
• The program’s page can be opened only from this computer (127.0.0.1), and a fresh access address is created each launch.

If your key is ever exposed, revoke it at build.nvidia.com immediately.

Where settings are kept

In the ~/.diffdock_batch/ folder — on Windows, C:\Users\<you>\.diffdock_batch\.
Your last options, output folder and the runtime environment (virtual environment) live there.

Deleting this folder resets the settings and the environment.
A key saved in the keychain is not in this folder, so remove it with Delete saved key.

Goes well with

• To sort a folder of lab photos and videos by date, see File Organizer.

Download — DiffDock Batch (Windows, macOS, Linux)