This document describes how to prepare for and install Toil. Note that Toil requires that the user run all commands inside of a Python virtualenv. Instructions for installing and creating a Python virtual environment are provided below.
Preparing Your Python Runtime Environment¶
It is recommended to install Toil into a virtual environment. This is useful for automatically deploying Python workflows, and is the only supported way to install Toil for Toil development.
If not already present, please install the latest Python
virtualenv using pip:
$ pip install --user virtualenv
And create a virtual environment called
venv somewhere convenient, usch as under
$ python3 -m virtualenv ~/venv
Now that you’ve created your virtualenv, activate your virtual environment:
$ source ~/venv/bin/activate
If all you want to do is run workflows, you can install Toil with frontends for CWL and WDL like this:
$ pip install toil[cwl,wdl]
If you need only the basic version of Toil for Python workflows, it can be installed like this:
$ pip install toil
Now you’re ready to run your first Toil workflow!
(If you need any more extra features, such as AWS support, don’t do this yet and instead see Installing Toil with Extra Features.)
Installing Toil with Extra Features¶
Some optional features, called extras, are not included in the basic installation of Toil. To install Toil with all its bells and whistles, first install any necessary headers and libraries (python-dev, libffi-dev). Then run
$ pip install toil[aws,google,mesos,encryption,cwl,wdl,kubernetes,server]
$ pip install toil[all]
Here’s what each extra provides:
Installs all extras (though htcondor is linux-only and will be skipped if not on a linux computer).
Provides support for managing a cluster on Amazon Web Service (AWS) using Toil’s built in Toil Cluster Utilities. Clusters can scale up and down automatically. It also supports storing workflow state.
Experimental. Stores workflow state in Google Cloud Storage.
Provides support for running Toil on an Apache Mesos
cluster. Note that running Toil on other batch systems
does not require an extra. The
If launching toil remotely on a mesos instance,
to install Toil with the
$ virtualenv ~/venv --system-site-packages
Otherwise, you’ll see something like this:
ImportError: No module named mesos.native
Support for the htcondor batch system. This currently is a linux only extra.
Provides client-side encryption for files stored in the AWS job store. This extra requires the following native dependencies:
Provides support for running workflows written using the Common Workflow Language.
Provides support for running workflows written using the Workflow Description Language. This extra has no native dependencies.
Provides support for running workflows written using a Kubernetes cluster.
Provides support for Toil server mode, including support for the GA4GH Workflow Execution Service API.
Some extras can’t install without additional dependencies. If you need any of these extras, make sure to install their dependencies first!
Building from Source¶
If developing with Toil, you will need to build from source. This allows changes you make to Toil to be reflected immediately in your runtime environment.
First, clone the source:
$ git clone https://github.com/DataBiosphere/toil.git
$ cd toil
Then, create and activate a virtualenv:
$ virtualenv venv
$ . venv/bin/activate
From there, you can list all available Make targets by running
First and foremost, we want to install Toil’s build requirements (these are
additional packages that Toil needs to be tested and built but not to be run):
$ make prepare
Now, we can install Toil in development mode (such that changes to the source code will immediately affect the virtualenv):
$ make develop
Or, to install with support for all optional Installing Toil with Extra Features:
$ make develop extras=[aws,mesos,google,encryption,cwl]
$ make develop extras=[all]
To build the docs, run
make develop with all extras followed by
$ make docs
To run a quick batch of tests (this should take less than 30 minutes) run
$ export TOIL_TEST_QUICK=True; make test
For more information on testing see Running Tests.