Hevo Airflow Provider Setup Guide

Last updated on Mar 26, 2026

The Hevo Airflow Provider enables you to run and manage Hevo Pipelines using Apache Airflow workflows. By installing this provider in your Airflow environment, you can trigger Pipeline syncs, monitor job execution, and coordinate data ingestion with other tasks in your workflow. Airflow also manages retries and alerts for these tasks, allowing you to respond to failures and control how tasks are executed.

This guide explains how to set up the Hevo Airflow Provider in different environments. You can choose one of the following setup methods depending on how you plan to install and run the provider:

Setup Method	Description	Recommended When
pip	The standard tool used to install and manage Python packages across various environments.	You prefer a traditional Python-based setup for installing and testing the provider locally.
UV	A Python tool that installs packages and their dependencies faster than `pip`.	You want a faster local development setup for installing and testing the provider locally.
Docker	A platform used to run applications in isolated environments.	You want to test the provider without installing Python dependencies directly on your system.

Prerequisites

Python version 3.9 or higher is installed.
A working Apache Airflow environment with version 2.4.0 or higher is set up.
Git is installed to clone the Hevo Airflow Provider repository.
Docker is installed if you need to run the Hevo Airflow Provider using the Docker-based setup.

Setup Using UV

Perform the following steps to install the Hevo Airflow Provider using UV:

Open a terminal window on your machine.
Run the following command to install the UV package manager:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
If you are using Homebrew, a package manager for macOS, run the following command:
```
brew install uv
```
Navigate to the location on your machine where you want to clone the Hevo Airflow Provider repository.

Run the following command to clone the repository:

git clone https://github.com/hevoio/hevo-airflow-provider.git

Navigate to the project that you want to integrate with the Hevo Airflow Provider.
If your project already has a Python virtual environment, proceed to step 7. If not, create one by running the following command:
```
uv venv
```
Activate the virtual environment.
```
source .venv/bin/activate
```
Run the following command to install the Hevo Airflow Provider in your project environment:
```
uv pip install -e /path/to/hevo-airflow-provider
```
Note: Replace /path/to/hevo-airflow-provider in the command above with the actual path to the cloned repository on your machine.

Setup Using pip

Perform the following steps to install the Hevo Airflow Provider using pip:

Open a terminal window on your machine.
Navigate to the location on your machine where you want to clone the Hevo Airflow Provider repository.

Run the following command to clone the repository:

git clone https://github.com/hevoio/hevo-airflow-provider.git

Navigate to the project that you want to integrate with the Hevo Airflow Provider.
If your project already has a Python virtual environment, proceed to step 6. If not, create one using Python version 3.9 or higher by running the following command:
```
python3 -m venv venv
```
Activate the virtual environment.
```
source venv/bin/activate
```
Run the following command to install the Hevo Airflow Provider in your project environment:
```
pip install -e /path/to/hevo-airflow-provider
```
Note: Replace /path/to/hevo-airflow-provider in the command above with the actual path to the cloned repository on your machine.

Setup Using Docker

Perform the following steps to run the Hevo Airflow Provider using Docker:

Open a terminal window on your machine.
Navigate to the location on your machine where you want to clone the Hevo Airflow Provider repository.

Run the following command to clone the repository:

git clone https://github.com/hevoio/hevo-airflow-provider.git

Navigate to the directory containing the Docker configurations for the Hevo Airflow Provider repository.
```
cd hevo-airflow-provider/docker
```
The repository contains Docker configurations for the following Apache Airflow versions:
- Apache Airflow 2.4
- Apache Airflow 3.0
Navigate to the directory corresponding to the Airflow version you want to use. For example, here, we are using Airflow version 3.0.
```
cd airflow-3.0
```
Ensure that Docker is running on your machine. If not, run the following command to start Docker Desktop:
```
open -a Docker
```
Run the following command to build the Docker image for the Hevo Airflow Provider:
```
docker build -t hevo-airflow-3.0 -f Dockerfile .
```
During the build process, Docker performs the following actions:
- Installs the specified Apache Airflow version.
- Installs the Hevo Airflow Provider so it can be tested and updated locally.
- Prepares the Airflow database required to run Airflow.
- Creates an administrator user named admin.
Navigate back to the Hevo Airflow Provider directory.
```
cd ../..
```
Run the following command to start the Airflow container:
```
docker run -d \
  --name hevo-airflow-3.0 \
  -p 8080:8080 \
  -e AIRFLOW__WEBSERVER__WEB_SERVER_HOST=0.0.0.0 \
  -v ./dag_examples:/opt/airflow/dag_examples \
  hevo-airflow-3.0
```
Note: If port 8080 is already in use on your machine, the container may fail to start. Stop the conflicting service or modify the port mapping in the command above. For example, replace -p 8080:8080 with -p 8081:8080. You can then access the Airflow UI at http://localhost:8081.
Run the following command to retrieve the password for the administrator user:
```
docker logs -f hevo-airflow-3.0 | grep -A 5 "admin"
```
Copy the password displayed in the terminal and save it securely on your machine. Use this password to log in to the Airflow UI.
From a web browser, access the Airflow UI at http://localhost:8080 and log in using the following credentials:

Note: If you modified the port mapping in step 9, access the Airflow UI using the updated port.
- Username: admin
- Password: The password retrieved in step 10.
(Optional) To view the container logs, run the following command in your terminal window:
```
docker logs -f hevo-airflow-3.0
```
(Optional) Run the following command to stop the Airflow container:
```
docker stop hevo-airflow-3.0
```

Once you have installed the Hevo Airflow Provider, you can verify the setup by triggering a Hevo Pipeline using Airflow. Refer to Using Edge Pipelines with Airflow for an end-to-end example of triggering and monitoring a Pipeline using Directed Acyclic Graphs (DAGs).

Revision History

Refer to the following table for the list of key updates made to this page:

Date	Release	Description of Change
Mar-26-2026	NA	New document.

Hevo Airflow Provider Setup Guide

On This Page

Prerequisites

Setup Using UV

Setup Using pip

Setup Using Docker

Revision History

Was this page helpful?

Tell us what went wrong