Getting Started#

Covalent is developed using Python 3.8 on Linux and macOS. See the Compatibility page for further details on Python versions and operating systems which support Covalent. To set up Python on your computer, refer to the official Python for Beginners page.


Upgrading Covalent#

If you are upgrading Covalent from the previous stable release, please refer to the migration guide if you wish to preserve your data and/or avoid any issues that may arise when upgrading.

Installation Methods#

Pip Install#

The easiest way to install Covalent is using the PyPI package manager:

pip install covalent


If you have used Covalent previously, make sure to uninstall the Covalent Dask plugin by running pip uninstall covalent-dask-plugin. That plugin has been folded into Covalent and will no longer be maintained separately.

Conda Install#

Users can also install Covalent as a package in a Conda environment:

conda install -c agnostiq covalent


Installation via Conda is currently only supported for Linux. Sometimes Conda can have trouble resolving packages. Use the flag --override-channels to speed things up.

Install From Source#

Covalent can also be downloaded and installed from source:

git clone
cd covalent

# Build dashboard
python webapp

# Install using pip (-e for developer mode), or...
pip install -e .

# Build and install using Conda (10-15 mins)
conda build .
conda install -c local covalent

The documentation can also easily be built locally:

python docs

Validate the Installation#

You can validate Covalent has been properly installed if the following returns without error:

python -c "import covalent"

Start the Server#

Use the Covalent CLI tool to manage the Covalent server. The following commands will help you get started.

$ covalent --help
Usage: covalent [OPTIONS] COMMAND [ARGS]...

Covalent CLI tool used to manage the servers.

-v, --version  Display version information.
--help         Show this message and exit.

logs     Show Covalent server logs.
purge    Shutdown server and delete the cache and config settings.
restart  Restart the server.
start    Start the Covalent server.
status   Query the status of the Covalent server.
stop     Stop the Covalent server.

Start the Covalent server:

$ covalent start
Covalent server has started at http://localhost:48008

Optionally, confirm the server is running:

$ covalent status
Covalent server is running at http://localhost:48008.

Now, navigate to the Covalent UI by entering the address into your web browser. This is where dispatched jobs will appear.

Hello, Covalent!#

Let’s look at a simple example to get started with Covalent. Before starting, ensure you have installed Covalent, verified the installation, and started the Covalent server. Next, open a Jupyter notebook or Python console and create a simple workflow:

import covalent as ct

# Construct tasks as "electrons"
def join_words(a, b):
    return ", ".join([a, b])

def excitement(a):
    return f"{a}!"

# Construct a workflow of tasks
def simple_workflow(a, b):
    phrase = join_words(a, b)
    return excitement(phrase)

# Dispatch the workflow
dispatch_id = ct.dispatch(simple_workflow)("Hello", "World")

Navigate to the Covalent UI at http://localhost:48008 to see your workflow in the queue:


Click on the dispatch ID to view the workflow graph:


While the workflow is being processed by the dispatch server, you are free to terminate the Jupyter kernel or Python console process without losing access to the results. Make sure the Covalent server remains in the β€œrunning” state while you have running workflows.

When the workflow has completed, you can start a new session and query the results:

import covalent as ct

dispatch_id = "8a7bfe54-d3c7-4ca1-861b-f55af6d5964a"
result_string = ct.get_result(dispatch_id).result

When you are done using Covalent, stop the server:

$ covalent stop
Covalent server has stopped.

Even if you forget to query or save your workflow results, Covalent saves them after each task’s execution. The full results, including metadata, are stored on disk in the format shown below:

πŸ“‚ my_project/
β”œβ”€ πŸ“™ my_experiment.ipynb
β”œβ”€ πŸ“‚ results/
β”‚  β”œβ”€ πŸ“‚ 8a7bfe54-d3c7-4ca1-861b-f55af6d5964a/
β”‚  β”‚  β”œβ”€ πŸ“„ result.pkl
β”‚  β”‚  β”œβ”€ πŸ—’οΈ
β”‚  β”‚  β”œβ”€ 🧾 result_info.yaml

Read more about how Covalent works on the Covalent concepts page.