Skip to main content

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.


Installation Methods

Pip Install

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

pip install covalent

Docker Install

Covalent can also run in Docker containers instead of covalent start:

git clone
cd covalent
docker compose up -d


The Docker image for Covalent is still being tested. Please open an issue on GitHub if you encounter unexpected behavior.

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


Users who wish to use the draw functionality outside of the UI may also wish to install graphviz and pygraphviz, either using Conda or Linux package managers. This is not required to use Covalent.

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.

config Get and set the configuration of services.
purge Shutdown server and delete the cache and config settings.
restart Restart the server(s).
status Return the statuses of the server(s).
stop Stop the server(s).

Start the Covalent server:

$ covalent start

Optionally, confirm the server is running:

$ covalent status

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:8000 to see your workflow in the queue:

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