Installation

This guide will help you install Graflow on your system.

System Requirements

• Python 3.9 or higher
• Docker (optional, for containerized tasks)

Installation Methods

pip

pip install graflow

uv

uv add graflow

Install with All Extras

To install Graflow with all optional dependencies:

pip

pip install "graflow[all]"

uv

uv add "graflow[all]"

graflow[all] includes the following extras:

Extra	Description
api	REST API server (FastAPI, Uvicorn)
visualization	Graph visualization (Matplotlib, Graphviz)
tracing	Observability (OpenTelemetry, Langfuse)
docker	Docker-based task execution
redis	Redis-backed distributed execution
adk	Google ADK agent integration
pydantic-ai	Pydantic AI agent integration

You can also install individual extras, e.g. graflow[visualization] or graflow[tracing].

pygraphviz requires system-level Graphviz

graflow[visualization] (and graflow[all]) depends on pygraphviz, which requires the Graphviz C libraries to be installed on your system before running pip install. Without them, the build will fail with an error like:

× Building wheel for pygraphviz (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> See above for output.

  note: This error originates from a subprocess, and is likely not a problem with pip.
  Building wheel for pygraphviz (pyproject.toml) ... error
  ERROR: Failed building wheel for pygraphviz
ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (pygraphviz)

Install Graphviz first using your system package manager:

macOS

brew install graphviz

Depending on your environment, you may also need to set the following environment variables so that pygraphviz can find the Graphviz headers and libraries:

export CFLAGS="-I$(brew --prefix graphviz)/include"
export LDFLAGS="-L$(brew --prefix graphviz)/lib"

Debian / Ubuntu

sudo apt install -y --no-install-recommends graphviz graphviz-dev

Verify Installation

After installation, verify that Graflow is installed correctly:

import graflow
print(graflow.__version__)

You should see the version number printed to the console.

Next Steps

Now that you have Graflow installed, let's create your first workflow in the Hello World tutorial.