If you are using the Anaconda scientific Python distribution, you already have the
conda package manager installed.
If not, the quickest way to get started is to install the Miniconda distribution, a lightweight, minimal installation of Python and the Conda package manager.
See the conda documentation for detailed installation instructions.
We recommend Miniforge, a drop-in replacement for Miniconda that uses the community-run
conda-forge channel by default.
Once Conda is installed, use it to install the OpenFF Toolkit:
$ conda install -c conda-forge openff-toolkit
Installation via the Conda package manager is the preferred method since all dependencies are automatically fetched and installed for you.
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 MacOS and Ubuntu Linux. For Windows support, we recommend using the Windows Subsystem for Linux (WSL) to run a Linux system integrated into Windows. We strongly suggest using WSL2, if your hardware supports it, for a smoother experience. WSL2 requires virtualization support in hardware. This is available on most modern CPUs, but may require activation in the BIOS.
Once WSL is configured, installing and using the Toolkit is done exactly as it would be for Linux. Note that by default, Jupyter Notebook will not be able to open a browser window and will log an error on startup; just ignore the error and open the link it provides in your ordinary Windows web browser.
Conda environments that mix packages from the default channels and
conda-forge can become inconsistent; to prevent this mixing, we recommend using
conda-forge for all packages. The easiest way to do this is to install Conda with Miniforge.
If you already have a complex environment, or you wish to install a version of the Toolkit that is incompatible with other software you have installed, you can install the Toolkit into a new environment:
$ conda create -c conda-forge --name offtk openff-toolkit
An environment must be activated in any new shell session to use the software installed in it:
$ conda activate offtk
To update an earlier
conda installation of
openff-toolkit to the latest release version, you can use
$ conda update -c conda-forge openff-toolkit
Note that this may update other packages or install new packages if the most recent release of the Toolkit requires it.
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
$ cd openff-toolkit $ python setup.py install
As of release 0.4.1, single-file installers are available for each Open Force Field Toolkit release.
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
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.
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.
You must have write access to the installation directory.
This is generally somewhere in the user’s home directory.
When prompted, we recommend NOT making modifications to your
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.
Any time you want to use this Conda environment in a terminal, run
$ source <install_directory>/etc/profile.d/conda.sh $ conda activate base
base environment is activated, your system will default to use Python (and other executables) from the newly installed Conda environment. For more information about Conda environments, see Conda environments
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.
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
The OpenFF Toolkit requires an external toolkit for most functions.
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 is a free and open source chemistry toolkit installed by default with the
It provides most of the functionality that the OpenFF Toolkit relies on.
AmberTools is a collection of free tools provided with the Amber MD software and installed by default with the
It provides a free implementation of functionality required by OpenFF Toolkit and not provided by RDKit.
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.
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.