Installation

Installing via conda

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

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

If you have Mamba installed, it is often faster:

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

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

$ conda activate openff-toolkit

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

Note

Installation via the Conda package manager is the preferred 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 .

Single-file installer

As of release 0.4.1, single-file installers are available for each Open Force Field Toolkit release. The single-file installer packages an entire Conda distribution complete will all dependencies needed to run the Toolkit. These are provided primarily for users who do not have access to the Anaconda cloud for installing packages. These installers have few requirements beyond a Linux or MacOS operating system and will, in one command, produce a functional Python executable containing the Open Force Field Toolkit, as well as all required dependencies. The installers are very similar to the widely-used Miniconda *.sh files. Accordingly, installation using the “single-file installer” does not require root access.

The installers are between 200 and 300 MB each, and can be downloaded from the “Assets” section of the Toolkit’s GitHub Releases page. They are generated using a workflow leveraging the Conda Constructor utility.

Please report any installer difficulties to the OFF Toolkit issue tracker, as we hope to make this a major distribution channel for the toolkit moving forward.

Installation

Download the appropriate installer (openff-toolkit-<X.Y.Z>-<py3x>-<your platform>-x86_64.sh.zip) from the “Assets” section at the bottom of the desired release on GitHub. Then, install the toolkit with the following command:

$ bash openff-toolkit-<X.Y.Z>-py37-<your platform>-x86_64.sh

and follow the prompts.

Note

You must have write access to the installation directory. This is generally somewhere in the user’s home directory. When prompted, we recommend NOT initializing the single-file installer.

Warning

We recommend that you do not install this package as root. Conda is intended to support on-the-fly creation of several independent environments, and managing a multi-user Conda installation is complicated.

Usage

Any time you want to use the single-file installer Conda environment in a terminal, run

$ source <install_directory>/etc/profile.d/conda.sh
$ conda activate base

Once the single-file installer base environment is activated, your shell session will use the Python installation (and any other provided executables) from it. Note that the single-file installer is a rare case in which we recommend altering the base environment, as the entire Conda distribution is centered on it. For more information about Conda environments, see Managing Environments.

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 builtin 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:

$ conda install -c openeye -c conda-forge 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:

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}