Installation

Installing via mamba

The simplest way to install the Open Force Field Toolkit is via Mamba, a drop-in replacement for the Conda package manager. We publish packages via conda-forge. With Mamba installed, use it to install the OpenFF Toolkit into a new environment:

$ mamba create -n openff-toolkit -c conda-forge openff-toolkit

To use the new environment in a shell session, you must first activate it:

$ mamba activate openff-toolkit

If you do not have Mamba or Conda installed, see the ecosystem installation documentation.

Note

Installation via the Mamba package manager is the recommended method since all dependencies are automatically fetched and installed for you.

OS support

The OpenFF Toolkit is pure Python, and we expect it to work on any platform that supports its dependencies. Our automated testing takes place on both (x86) MacOS and Ubuntu Linux.

Installing from source

The OpenFF Toolkit has a lot of dependencies, so we strongly encourage installation with a package manager. The developer’s guide describes setting up a development environment. If you’re sure you want to install from source, check the conda-forge recipe for current dependencies, install them, download and extract the source distribution from GitHub, and then run pip:

$ cd openff-toolkit
$ python -m pip install .

Optional dependencies (toolkits)

The OpenFF Toolkit outsources many common computational chemistry algorithms to other toolkits. Only one such toolkit is needed to gain access to all of the OpenFF Toolkit’s features. If more than one is available, the Toolkit allows the user to specify their preference with the toolkit_registry argument to most functions and methods.

The openff-toolkit package installs everything needed to run the toolkit, including the optional dependencies RDKit and AmberTools. To install only the hard dependencies and provide your own optional dependencies, install the openff-toolkit-base package.

The OpenFF Toolkit requires an external toolkit for most functions. Though a “built-in” toolkit is provided, it implements only a small number of functions and is intended primarily for testing.

There are certain differences in toolkit behavior between RDKit/AmberTools and OpenEye when reading a small fraction of molecules, and we encourage you to report any unexpected behavior that may be caused by toolkit differences to our issue tracker.

RDKit

RDKit is a free and open source chemistry toolkit installed by default with the openff-toolkit package. It provides most of the functionality that the OpenFF Toolkit relies on.

AmberTools

AmberTools is a collection of free tools provided with the Amber MD software and installed by default with the openff-toolkit package. It provides a free implementation of functionality required by OpenFF Toolkit and not provided by RDKit.

OpenEye

The OpenFF Toolkit can optionally make use of the OpenEye toolkit if the user has a license key installed. Academic laboratories intending to release results into the public domain can obtain a free license key, while other users (including academics intending to use the software for purposes of generating protected intellectual property) must pay to obtain a license.

To install the OpenEye toolkits:

$ mamba install -c openeye openeye-toolkits

Though OpenEye can be installed for free, using it requires a license file. No essential openff-toolkit release capabilities require the OpenEye toolkit, but the Open Force Field developers make use of it in parameterizing new open source force fields.

Check installed toolkits

All available toolkits are automatically registered in the GLOBAL_TOOLKIT_REGISTRY. The available toolkits and their versions can be inspected through the registered_toolkit_versions dictionary attribute:

from openff.toolkit import GLOBAL_TOOLKIT_REGISTRY

print(GLOBAL_TOOLKIT_REGISTRY.registered_toolkit_versions)
# {'The RDKit': '2022.03.5', 'AmberTools': '22.0', 'Built-in Toolkit': None}