> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AutoDock Vina

> [AutoDock Vina](https://github.com/ccsb-scripps/AutoDock-Vina) predicts how a small molecule can bind within a specified region of a rigid receptor. This toolkit prepares receptor and ligand PDBQT models with Meeko, runs Vina or Vinardo scoring on CPU, and returns ranked poses with affinity scores, RMSD bounds, bond-correct SDF and PDBQT exports, and preparation provenance including residue-template assignments and ligand-minimization convergence.

![AutoDock Vina](https://proto-bio.github.io/proto-assets/images/tool/vina/hero.png)[![](https://mintcdn.com/bio-pro/2KNs-ARSUr3ypt0h/assets/images/cached/fa61cb4f1189.png?fit=max\&auto=format\&n=2KNs-ARSUr3ypt0h\&q=85\&s=c48936b823339f7c1649760e1c21e9a9) Scripps Research](https://proto.evodesign.org/docs/tools/organizations/scripps-research.md) [![](https://mintcdn.com/bio-pro/2KNs-ARSUr3ypt0h/assets/images/cached/bc5ca659e459.png?fit=max\&auto=format\&n=2KNs-ARSUr3ypt0h\&q=85\&s=53e1a96eaa8ad2a4f1086848f98abbeb) Forli Lab](https://proto.evodesign.org/docs/tools/organizations/forli-lab.md)

Proto is not affiliated with Scripps Research and the Forli Lab. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.

***

&#x20;GitHub GitHub  Website Website  Publication Publication  Cite Cite  Tool Source Tool Source  Open as Notebook Open as Notebook  Run Locally Run Locally

![ccsb-scripps/AutoDock-Vina](https://opengraph.githubassets.com/1/ccsb-scripps/AutoDock-Vina)

&#x20;ccsb-scripps/AutoDock-Vina

&#x20;View repo

[Open](https://github.com/ccsb-scripps/AutoDock-Vina)

![](https://mintcdn.com/bio-pro/2EYBBzZYWyVjl8bI/assets/images/site-previews/vina_scripps_edu.jpg?fit=max\&auto=format\&n=2EYBBzZYWyVjl8bI\&q=85\&s=1dd0e74da25eae10c5c6fde7efa7a9df)

&#x20;vina.scripps.edu

&#x20;Visit website

[Open](https://vina.scripps.edu)

AutoDock Vina 1.2.0: New Docking Methods, Expanded Force Field, and Python BindingsJerome Eberhardt, Diogo Santos-Martins, ... Stefano ForliJournal of Chemical Information and Modeling (2021)

&#x20;Read paper

[Open](https://doi.org/10.1021/acs.jcim.1c00203)

@articleeberhardt2021autodockvina\@articletrott2010autodockvina\@articlesantosmartins2025meeko+2 more

```bibtex theme={null}
@article{eberhardt2021autodockvina,
  title={{AutoDock Vina 1.2.0}: New Docking Methods, Expanded Force Field, and Python Bindings},
  author={Eberhardt, Jerome and Santos-Martins, Diogo and Tillack, Andreas F. and Forli, Stefano},
  journal={Journal of Chemical Information and Modeling},
  volume={61},
  number={8},
  pages={3891--3898},
  year={2021},
  publisher={American Chemical Society},
  doi={10.1021/acs.jcim.1c00203}
}

@article{trott2010autodockvina,
  title={{AutoDock Vina}: Improving the Speed and Accuracy of Docking with a New Scoring Function, Efficient Optimization, and Multithreading},
  author={Trott, Oleg and Olson, Arthur J.},
  journal={Journal of Computational Chemistry},
  volume={31},
  number={2},
  pages={455--461},
  year={2010},
  publisher={Wiley},
  doi={10.1002/jcc.21334}
}

@article{santosmartins2025meeko,
  title={Meeko: Molecule Parametrization and Software Interoperability for Docking and Beyond},
  author={Santos-Martins, Diogo and He, Yiran and Eberhardt, Jerome and Sharma, Parnika and Bruciaferri, Niccolo and Holcomb, Matthew and Llanos, Manuel A. and Hansel-Harris, Althea and Barkdull, Allison Pearl and Tillack, Andreas Frank and Bianco, Giulia and Paulsen, May-Linn and Mato, Joani and Taneja, Ishan and Forli, Stefano},
  journal={Journal of Chemical Information and Modeling},
  volume={65},
  number={24},
  pages={13045--13050},
  year={2025},
  publisher={American Chemical Society},
  doi={10.1021/acs.jcim.5c02271}
}

@article{quiroga2016vinardo,
  title={Vinardo: A Scoring Function Based on {AutoDock Vina} Improves Scoring, Docking, and Virtual Screening},
  author={Quiroga, Rodrigo and Villarreal, Marcos A.},
  journal={PLOS ONE},
  volume={11},
  number={5},
  pages={e0155183},
  year={2016},
  publisher={Public Library of Science},
  doi={10.1371/journal.pone.0155183}
}

@article{nagar2002abl,
  title={Crystal Structures of the Kinase Domain of {c-Abl} in Complex with the Small Molecule Inhibitors {PD173955} and Imatinib ({STI-571})},
  author={Nagar, Bhushan and Bornmann, William G. and Pellicena, Patricia and Schindler, Thomas and Veach, Darren R. and Miller, W. Todd and Clarkson, Bayard and Kuriyan, John},
  journal={Cancer Research},
  volume={62},
  number={15},
  pages={4236--4243},
  year={2002},
  publisher={American Association for Cancer Research},
  pmid={12154025},
  url={https://pubmed.ncbi.nlm.nih.gov/12154025/}
}
```

&#x20;Copy citation

![Proto](https://mintcdn.com/bio-pro/cMLt8hAqaP9M3LKy/assets/logo/logo-light.svg?fit=max\&auto=format\&n=cMLt8hAqaP9M3LKy\&q=85\&s=f5e5dfd1b8f9b9db3a0be0e2eb01f678)

evo-design/proto-tools

&#x20;View source

[Open](https://github.com/evo-design/proto-tools/tree/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina)

Open Notebook

&#x20;Open notebook

[Open](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/examples/example.ipynb)

[![proto-tools on GitHub](https://opengraph.githubassets.com/1/evo-design/proto-tools)](https://github.com/evo-design/proto-tools)

Run locally with proto-tools

```bash theme={null}
pip install git+https://github.com/evo-design/proto-tools.git
```

Toolkit contributors[![](https://avatars.githubusercontent.com/u/61667248?v=4\&s=64)adititm](https://github.com/adititm)[![](https://avatars.githubusercontent.com/u/21143637?v=4\&s=64)bviggiano](https://github.com/bviggiano)[![](https://avatars.githubusercontent.com/u/101753425?v=4\&s=64)jaeHbk](https://github.com/jaeHbk)

| Function | Description | |
| - | - | - |
| `run_vina_docking()` | Dock a small molecule into a rigid receptor with AutoDock Vina or Vinardo scoring. | [ Docs](#api-run-vina-docking) [ Source](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/vina_docking.py#L563) |

> [!NOTE]
>
> **License:** AutoDock Vina's own code is licensed under Apache-2.0, and it federates over bundled data sources and components, each under its own license terms.
>
> Bundled dependencies, each under its own license:
>
> * [Meeko](https://github.com/forlilab/Meeko/blob/develop/LICENSE): Custom (LGPL-2.1-or-later)
> * [RCSB Protein Data Bank fixture data](https://www.rcsb.org/pages/policies): CC0-1.0
>
> Review each source's terms before commercial use or redistribution.

## Background

AutoDock Vina ([Trott and Olson, 2010](https://doi.org/10.1002/jcc.21334)) combines a knowledge-inspired scoring function with iterated local search to explore ligand translations, orientations, and rotatable bonds inside a user-defined three-dimensional grid. Vina 1.2 ([Eberhardt et al., 2021](https://doi.org/10.1021/acs.jcim.1c00203)) added Python bindings, expanded atom typing, and support for the Vinardo scoring function ([Quiroga and Villarreal, 2016](https://doi.org/10.1371/journal.pone.0155183)).

Docking requires two distinct decisions: the chemical state of the molecules and the region to search. The receptor remains rigid, while Vina samples the ligand's movable torsions. Meeko ([Santos-Martins et al., 2025](https://doi.org/10.1021/acs.jcim.5c02271)) assigns AutoDock atom types and partial charges, writes PDBQT inputs, and reconstructs each predicted pose as an SDF record with the ligand's original bond orders.

The reported affinity is a docking score in kcal/mol. More negative scores rank more favorably within the same receptor, ligand, box, and scoring setup, but they are not calibrated experimental binding free energies. The RMSD lower and upper bounds measure each returned mode's distance from the best predicted mode; they are not RMSDs against a crystallographic reference pose. Docking is most useful for generating plausible binding hypotheses, enriching a virtual-screening shortlist, or comparing poses before higher-cost simulation or experimental validation.

The bundled receptor and reference-ligand fixtures are derived from chain A of RCSB PDB entry [1IEP](https://www.rcsb.org/structure/1IEP), the c-Abl/imatinib complex reported by [Nagar et al. (2002)](https://pubmed.ncbi.nlm.nih.gov/12154025/). RCSB PDB archive data is distributed under CC0-1.0.

### Learning Resources

* [AutoDock Vina documentation](https://autodock-vina.readthedocs.io/en/latest/) - official installation, docking, and scoring documentation.
* [AutoDock Vina repository](https://github.com/ccsb-scripps/AutoDock-Vina) - source code, releases, and issue tracker.
* [Meeko repository](https://github.com/forlilab/Meeko) - receptor and ligand preparation implementation used by this toolkit.

## Tools

### AutoDock Vina Docking (`vina-docking`)

Prepares one rigid receptor and one or more small-molecule ligands, searches either an explicit box or a box derived from a coordinate-bearing reference ligand, and returns the ranked poses retained by Vina for each ligand. Bare SMILES strings are accepted, and a single ligand is normalized into a one-element list; the tool generates a seeded three-dimensional conformer per ligand before docking.

#### API Reference

[ Source](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/vina_docking.py#L156)

> [accordion] Input: VinaDockingInput
>
> **receptor** `Structure` *required*
>
> Receptor coordinates to parameterize as a rigid PDBQT model.
>
> **Structure**
>
> **structure** `string` *required*
>
> Raw structure content in PDB or CIF format.
>
> **structure\_format** `string`
>
> Format of the content string (auto-detected if omitted).
>
> **b\_factor\_type** `BFactorType` (default: unspecified)
>
> What the B-factor column represents.
>
> **source** `string`
>
> Optional source identifier (filepath or tool name).
>
> **metrics** `Metrics`
>
> Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.
>
> **ligands** `List[Fragment]` *required*
>
> Small molecules to dock against the receptor, each scored independently. SMILES strings are accepted, and a single ligand is normalized into a one-element list.
>
> **Fragment**
>
> **id** `string`
>
> Optional identifier (free-form; e.g. a chain letter for in-complex use).
>
> **smiles** `string`
>
> SMILES string (canonicalized to RDKit form on construction).
>
> **ccd\_code** `string`
>
> CCD code from the Chemical Component Dictionary.
>
> **entity\_type** `string` (default: ligand)
>
> Always `"ligand"`. Lets Fragments be used interchangeably with `Chain` in structure-prediction inputs.
>
> **name** `string`
>
> Human-readable molecule name.
>
> **metrics** `Dict[string, number]`
>
> Computed metrics for this fragment.
>
> **search\_box** `VinaSearchBox | VinaReferenceLigandBox` *required*
>
> Explicit search box or a box derived from a reference ligand in the receptor coordinate frame.

[ Source](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/vina_docking.py#L438)

> [accordion] Config: VinaDockingConfig
>
> **scoring\_function** `enum` (default: vina)
>
> Vina-family scoring function.
>
> Available options: `vina`, `vinardo`
>
> **exhaustiveness** `integer` (default: 8)
>
> Number of independent Monte Carlo search runs.
>
> **num\_poses** `integer` (default: 9)
>
> Maximum poses retained and returned.
>
> **energy\_range** `number` (default: 3.0)
>
> Maximum affinity difference from the best returned pose.
>
> **min\_rmsd** `number` (default: 1.0)
>
> Minimum RMSD separation between retained poses.
>
> **max\_evaluations** `integer` (default: 0)
>
> Search evaluation cap; zero uses Vina's heuristic.
>
> **cpu** `integer` (default: 0)
>
> Worker threads; zero lets Vina use all available CPUs.
>
> **grid\_spacing** `number` (default: 0.375)
>
> Affinity-map grid spacing in angstroms.
>
> **allow\_bad\_residues** `boolean` (default: False)
>
> Delete receptor residues Meeko cannot parameterize.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cpu)
>
> Device to run the tool on.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `integer`
>
> Positive signed 32-bit seed; generated and returned when omitted.

[ Source](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/vina_docking.py#L339)

> [accordion] Output: VinaDockingOutput
>
> **results** `List[VinaLigandResult]` *required*
>
> One entry per input ligand, in input order.
>
> **VinaLigandResult**
>
> **smiles** `string` *required*
>
> SMILES of the docked ligand, echoed for provenance.
>
> **seed** `integer` *required*
>
> Seed actually used for this ligand, advanced from the request seed by the ligand's position so duplicate ligands still sample independently.
>
> **poses** `List[VinaDockingPose]` *required*
>
> Ranked poses in ascending affinity order.
>
> **poses\_sdf** `string` *required*
>
> This ligand's returned poses in a combined SDF payload.
>
> **poses\_pdbqt** `string` *required*
>
> This ligand's returned poses in a combined PDBQT payload.
>
> **optimization\_method** `string`
>
> Force field used to minimize the input conformer.
>
> **optimization\_converged** `boolean`
>
> Whether conformer minimization converged.
>
> **optimization\_attempts** `integer`
>
> Conformer minimization attempts made.
>
> **optimization\_iteration\_limits** `List[integer]`
>
> Iteration cap used for each attempt.
>
> **warnings** `List[string]`
>
> Ligand-specific preparation warnings.
>
> **seed** `integer` *required*
>
> Concrete random seed used by Vina and ligand conformer generation.
>
> **search\_box** `VinaSearchBox` *required*
>
> Resolved search-box coordinates.
>
> **VinaSearchBox**
>
> **mode** `string`
>
> Use an explicitly positioned search box.
>
> **center** `array` *required*
>
> Box center `(x, y, z)` in angstroms.
>
> **size** `array` *required*
>
> Positive box dimensions `(x, y, z)` in angstroms.
>
> **scoring\_function** `enum` *required*
>
> Scoring function used.
>
> **Metrics** (one set per `results` item)
>
> | Metric | Type | Range | Availability |
> | - | - | - | - |
> | `affinity` | float | unbounded | always |
> | `rmsd_lower_bound` | float | ≥ 0.0 | always |
> | `rmsd_upper_bound` | float | ≥ 0.0 | always |

#### Applications

Use this tool for redocking a known ligand into an experimental receptor, proposing binding modes for analogs, screening a focused set of compounds against a defined pocket, or producing initial protein-ligand poses for molecular dynamics and free-energy workflows. It is also useful for checking whether a designed pocket can accommodate a candidate ligand without severe steric conflicts.

#### Usage Tips

* **Define the search box from pocket evidence.** Use `VinaSearchBox` when a known pocket center is available. Use `VinaReferenceLigandBox` when a co-crystallized ligand is aligned to the receptor; `padding` is added on both sides of each ligand axis.
* **Keep the box focused but large enough for the ligand.** An oversized box makes the search less efficient, while a box that clips the ligand or pocket can exclude valid poses. A 20 to 25 angstrom box is a common starting point for drug-like ligands.
* **Stay within the grid-allocation limits.** Each box axis is limited to 100 angstroms, `grid_spacing` must be at least 0.1 angstrom, and the resolved map may contain at most 2,000,000 grid points. Increase spacing or reduce the box when validation reports a larger allocation.
* **Prepare the receptor's chemical state deliberately.** Resolve missing atoms, alternate locations, protonation states, cofactors, metals, and waters before docking. Meeko adds missing hydrogens from its residue templates but does not perform environment-aware pKa prediction; a hydrogen-free ambiguous histidine can therefore receive the default `HIE` template. Inspect `receptor_template_assignments` in output metadata. Unsupported residues fail by default; `allow_bad_residues=True` deletes residues Meeko cannot parameterize, reports their identifiers in `ignored_receptor_residues`, and emits a warning.
* **Encode ligand protonation and stereochemistry in the SMILES.** The tool preserves the input graph, generates a new seeded conformer, and minimizes it with MMFF94 or UFF when parameters are available. It does not enumerate tautomers, protonation states, or undefined stereocenters; an undefined center may produce one seed-dependent geometry. Specify stereochemistry explicitly and evaluate each intended chemical state as a separate input.
* **Pass a whole ligand set in one call.** `ligands` is the per-item field, so a screen is fanned out and cached per ligand rather than per call. Receptor preparation is the expensive setup step and depends only on the receptor, so it runs once and is reused for every ligand in a request. Results are returned in input order, one entry per ligand. Each ligand advances the request seed by its position, so duplicate ligands in one call still sample independently while a given (seed, position) stays reproducible.
* `visualize_search_box(inputs, config)` in `helpers.py` draws the receptor with the resolved search box, and the reference ligand when the box was derived from one, so a misplaced or undersized box is visible before the run. Passing the config also reports the affinity-map grid size and flags an oversized grid up front rather than at dispatch.
* **Increase `exhaustiveness` for production searches.** The default of 8 is suitable for an initial run. Larger or more flexible ligands often need repeated seeds and higher exhaustiveness to establish that the top-ranked pose is stable.
* **Use `seed` for exact reruns.** When omitted, the framework generates a positive signed 32-bit seed and returns it in the output. Reuse the returned seed with the same environment and configuration to reproduce the search.
* **Treat affinity as a ranking signal, not an absolute binding measurement.** Compare scores only across chemically and procedurally consistent runs, and inspect interactions and pose plausibility before drawing conclusions.
* **Use SDF for downstream chemistry workflows.** Each pose and the combined result are returned as SDF with reconstructed bond orders. PDBQT is also retained for AutoDock interoperability and auditability.

## Toolkit Notes

These apply to every AutoDock Vina tool in this toolkit (`vina-docking`).

* **The first local call creates an isolated environment.** It installs Vina 1.2.7 from conda-forge and pinned Meeko 0.7.1, after which the environment is reused. Conda-forge supplies Vina builds for supported Linux and macOS architectures. Persistent execution avoids repeated worker startup and chemistry-library imports across a docking batch.
* **Docking is CPU-only.** `cpu=0` lets Vina use all visible CPUs; set a positive value to bound each run's thread consumption. GPU device settings do not accelerate this toolkit.
* **Within one call, ligands are docked one after another.** `cpu` bounds the threads Vina uses for a single ligand's search, so throughput across a set comes from that per-ligand threading rather than from ligands running concurrently. Receptor preparation is hoisted out of the loop and paid once per call. To use more cores than one search can saturate, split the set across parallel calls; `max_chunk_size` caps how many ligands the framework sends to a worker at a time.
* **The receptor is rigid.** Side-chain or backbone flexibility, covalent docking, explicit-solvent sampling, and induced-fit refinement are outside this tool's scope.
* **Outputs include complete provenance needed to repeat a run.** The concrete seed, resolved box, effective search controls, Vina, Meeko, and RDKit versions, requested pose count, ligand count, and receptor omissions and template assignments are returned at the top level, while each ligand's minimization convergence, warnings, poses, and SDF/PDBQT payloads live on that ligand's result.

> [!TIP]
>
> **Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/227cc79a2cac070aa69c91f60660e353d7f84a53/proto_tools/tools/molecular_docking/vina/examples/example.ipynb) for a copy-paste-ready walkthrough.

## Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

> [card] [Tool Persistence](https://proto.evodesign.org/docs/tools/guides/tool-persistence.md)
>
> Keep a tool's model warm across calls instead of reloading it every invocation.

> [card] [Device Management](https://proto.evodesign.org/docs/tools/guides/device-management.md)
>
> How GPUs are allocated to tools and how to target specific devices.

> [card] [Parallel Execution](https://proto.evodesign.org/docs/tools/guides/parallel-execution.md)
>
> Fan a batch of inputs out across multiple GPUs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.