Get Hydra on your machine

Install Hydra

Hydra is one Python package on PyPI. A single command installs the engine and the hdrctl command line. The API server, the Studio and the database connectors are extras you add only when you need them.

$ pip install hydra-etl

Requires Python 3.9 or later. Package page: pypi.org/project/hydra-etl

Before you start

Python 3.9 or laterCheck with python --version

pip, up to dateRefresh with python -m pip install --upgrade pip

Git — source install onlyNeeded to clone the repository

Activate an environment

The one command that differs per terminal

macOS / Linuxsource .venv/bin/activate

Windows — PowerShell.\.venv\Scripts\Activate.ps1

Windows — cmd.exe.venv\Scripts\activate.bat

Read this before you run any command

Every command on this page installs software on your machine, with your own rights. Three habits make that safe — here and anywhere else.

Install from a source you can name. On this page that means PyPI for hydra-etl, the Hydra repository on GitHub for the source build, GitHub Container Registry for the image, and astral.sh for uv. Nothing else.
Never pipe a remote script into a shell before reading it. curl … | sh and irm … | iex download code and execute it in the same breath, leaving you no chance to look at it. Open the URL in a browser and read it first — or use a package manager such as brew, winget or pip, which spares you the trade-off entirely.
Check what actually landed. pip show hydra-etl prints the version and the exact install location, so you can confirm you got what you asked for.

Installation paths

Pick the one that matches what you need

The CLI and the engine

AVAILABLE

The default path. Installs hdrctl and the execution engine — enough to write a manifest and run a job on files.

# create an isolated environment, then activate it
$ python -m venv .venv
$ source .venv/bin/activate

$ pip install hydra-etl

The virtual environment is optional but recommended: it keeps Hydra and its dependencies away from your system Python.

With the API and the Studio

AVAILABLE

Adds the HTTP server and unlocks hdrctl serve, which starts the API and the visual canvas. The Studio ships inside the package — no Node, no separate download.

$ pip install "hydra-etl[server]"
$ hdrctl serve

# Studio and API on http://127.0.0.1:5678

Keep the quotes around "hydra-etl[server]": zsh and PowerShell read the square brackets as their own syntax.

From the repository

AVAILABLE

For reading the connectors, following unreleased changes or contributing. The editable install keeps hdrctl pointed at your working copy.

$ git clone https://github.com/andaluzlab/hydra.git
$ cd hydra
$ pip install -e ".[all]"

Editable mode: any change in the source tree is picked up on the next hdrctl call.

Container image

AVAILABLE

Run the CLI, API and bundled Studio without installing Python or Node. The official image is published on GitHub Container Registry.

$ docker pull ghcr.io/bejaouibechir/hydra:0.9.6
$ docker run --rm -p 5678:5678 -v hydra-workspace:/workspace ghcr.io/bejaouibechir/hydra:0.9.6

Open http://localhost:5678. Your projects remain in the hydra-workspace Docker volume after the container stops.

With uv, without a virtual environment

THIRD PARTY

uv installs Hydra as a standalone tool: it provisions its own Python, keeps it isolated and puts hdrctl on your PATH. Nothing to activate — the path with the fewest steps to get wrong.

uv is built by Astral, not by the Hydra team. We do not control its releases and cannot vouch for its content. Install it through a package manager you already trust, rather than through the curl | sh bootstrap advertised on its own site.

# 1. install uv once, with the package manager you already use
$ brew install uv
#    Windows        : winget install --id=astral-sh.uv -e
#    Python present : pip install uv

# 2. install Hydra as an isolated tool
$ uv tool install "hydra-etl[server]"

If hdrctl is still not found, run uv tool update-shell and open a new terminal.

Install with Docker

Hydra Core, CLI, API and Studio in one image

Before you start Install Docker Desktop, or Docker Engine on Linux, and make sure docker version can reach the server.

Download the image

Use the versioned tag for a reproducible installation.

docker pull ghcr.io/bejaouibechir/hydra:0.9.6

Start Hydra Studio

Publish port 5678 and keep projects in a named Docker volume.

docker run --rm -p 5678:5678 -v hydra-workspace:/workspace ghcr.io/bejaouibechir/hydra:0.9.6

When the container is healthy, open http://localhost:5678. Stop it with Ctrl+C; the workspace volume is preserved.

Use the CLI on a local project

Mount the current folder at /project. On PowerShell, ${PWD} resolves to your current directory.

docker run --rm -v "${PWD}:/project" -w /project ghcr.io/bejaouibechir/hydra:0.9.6 hdrctl validate .

docker run --rm -v "${PWD}:/project" -w /project ghcr.io/bejaouibechir/hydra:0.9.6 hdrctl run .

Verify and update

Confirm the packaged CLI, then pull the tag again whenever a new Hydra image is released.

docker run --rm ghcr.io/bejaouibechir/hydra:0.9.6 hdrctl --version

Image tags. Use 0.9.6 in production or CI so every pull resolves to the intended release. Use latest only when you explicitly want the newest published version.

Verify the installation

Run this from any folder except the Hydra source tree

$ hdrctl --version
hydra 0.9.6  |  Hydra ETL Framework  |  Python 3.12.0

$ hdrctl --help

What you just installed

One package, four surfaces

CLI

hdrctl

Scaffolds, validates, runs and lists your jobs and workflows. Also available as hydra.

ENGINE

Execution engine

Reads the manifests, resolves connectors and executes the steps in declared order.

API

API server

Serves the same jobs over HTTP so schedulers and services can trigger a run. Needs the server extra.

Hydra Studio

The visual canvas, bundled inside the package. Started by hdrctl serve with the server extra.

Optional extras

Written as pip install "hydra-etl[name]"

Extra	What it adds	Add it when
`server`	API server, scheduler and Hydra Studio	You want the visual canvas or you trigger runs over HTTP
`postgres`	PostgreSQL connector	A source or a destination is a PostgreSQL database
`mysql`	MySQL connector	A source or a destination is a MySQL database
`mongodb`	MongoDB connector	A source or a destination is a MongoDB collection
`duckdb`	DuckDB connector	You query files with SQL, or use DuckDB as a local warehouse
`parquet`	Parquet read and write	Your files are Parquet rather than CSV or JSON
`http`	HTTP and REST connector	A source is a web API
`all`	Everything above, in one command	You are exploring and do not want to pick yet

If something goes wrong

The five failures we see most

hdrctl: command not found

The environment is not active, or the terminal still holds an older PATH. Activate the environment, then check which binary answers:

$ which hdrctl        # macOS, Linux
$ where.exe hdrctl    # Windows

The path must point inside your .venv. If it does not, open a new terminal and activate again.

pip says "Requirement already satisfied" and downloads nothing

You are installing into the system Python, not into the environment. The prompt must show (.venv) before you run pip. If it does not, the activation step silently failed — see the next entry.

On Windows, the activation script does nothing or raises a SyntaxError

Each terminal has its own script, and activate is never run through Python. In PowerShell use .\.venv\Scripts\Activate.ps1; in cmd.exe use .venv\Scripts\activate.bat. If PowerShell refuses to run scripts, allow it for that window only:

PS> Set-ExecutionPolicy -Scope Process RemoteSigned

ModuleNotFoundError when hdrctl starts

An older Hydra is installed in your system Python and its launcher shadows the new one. Remove it outside any environment, then open a new terminal:

$ pip uninstall hydra-etl

Nothing works when I test inside the Hydra source folder

Python imports the local hydra_etl/ directory instead of the installed package, so you are never testing what your users get. Run the verification from any other folder.

Once installed

Install and verifyThe CLI lesson that walks through the same steps in detail. Build your first jobCSV in, two operations, CSV out — the complete guided example. Read the grammarEvery manifest block, field by field.