Installation

Ginkgo needs Python 3.11 or later.

To write and run workflows, use the curl installer. It is the route for most readers. To work on Ginkgo itself, clone the repository and use Pixi, as shown in the last section of this page.

Quick Install (curl)

Install the ginkgo command in one line. This needs uv:

curl -LsSf https://raw.githubusercontent.com/sanjaynagi/ginkgo/main/install.sh | sh

This installs Ginkgo and its Pixi plugin from PyPI, into an isolated environment that uv manages. Run the same command again to upgrade.

The package on PyPI is ginkgo-workflow. The command and the Python import are both ginkgo. To install it into an existing environment instead:

pip install ginkgo-workflow

The installer gives you only the ginkgo command. The example workflows are not included. To get them, clone the repository:

git clone https://github.com/sanjaynagi/ginkgo.git

Verify The CLI

Check that the ginkgo command works:

ginkgo --help

Plugins

Extra features come as plugins, which you install as extras of ginkgo-workflow. Each extra is named after its plugin without the ginkgo- prefix, so ginkgo-k8s is ginkgo-workflow[k8s]. The curl installer includes ginkgo-pixi.

Plugin	Adds
ginkgo-pixi	Pixi environments (env="name") and the ginkgo env command
ginkgo-notebook	@task("notebook"), for marimo notebooks. Projects from ginkgo init list it in their pixi.toml
ginkgo-report	the ginkgo report command, for HTML run reports
ginkgo-slack	run notifications to Slack
ginkgo-k8s	the Kubernetes executor
ginkgo-gcp	gs:// storage and the GCP Batch executor
ginkgo-aws	s3:// storage
ginkgo-oci	oci:// storage (Oracle Cloud Object Storage)

The oci:// container images in a task’s env= need no plugin.

To install Ginkgo with every first-party plugin:

uv tool install --force "ginkgo-workflow[all]"

To pick plugins, list them as extras. Keep pixi in the list, because --force replaces the plugins the tool had before:

uv tool install --force "ginkgo-workflow[pixi,k8s]"

ginkgo plugins lists what is installed. If a task needs a missing plugin, Ginkgo names it. Remote Execution explains how to set up an executor.

Runtime Prerequisites

Ginkgo builds the environments your tasks declare. To do that, it runs pixi, docker or podman on your computer. Each program must be on your PATH when you run a workflow that uses it:

• pixi, for tasks that declare a Pixi or Conda environment. Install it from pixi.sh. Ginkgo runs pixi install for you on first use.
• docker or podman, for tasks that declare a docker:// or oci:// image. Ginkgo pulls the image for you on first use.

You need neither if your workflow declares no environments. See Environments.

Python tasks run in the same Python environment as the ginkgo command, so install any package they import there. See Python Tasks Run In The CLI’s Own Environment.

Editable Python Install

To use a plain Python environment instead, clone the repository and install from the clone:

git clone https://github.com/sanjaynagi/ginkgo.git
cd ginkgo
pip install -e .
pip install -e plugins/ginkgo-k8s plugins/ginkgo-gcp   # optional executors

This installs the ginkgo command.

Install For Ginkgo Development (Pixi)

The repository’s pyproject.toml sets up Pixi for working on Ginkgo itself. From a clone, install the environment and use Pixi to run the tests and build the docs:

pixi install
pixi run test
pixi run docs-build

The default environment installs every first-party plugin in editable mode, so pixi run test tests the core and the plugins. The core environment has no plugins. Run pixi run -e core test-core to test the core alone.

To check the CLI in this setup, run:

pixi run python -m ginkgo.cli --help