# argoproj-labs/hera: Writing Argo Workflows in Python instead of YAML

> Hera is the Python SDK that turns functions into Argo Workflows templates and submits them to a cluster. It fits teams already running Argo Workflows who want orchestration in typed Python, and it is the wrong choice if you have no Argo server.

**argoproj-labs/hera** — Hera makes Python code easy to orchestrate on Argo Workflows through native Python integrations. It lets you construct and submit your Workflows entirely in Python. ⭐️ Remember to star!

- Repository: https://github.com/argoproj-labs/hera
- Website: https://hera.rtfd.io
- Stars: 940 · Forks: 128
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/argoproj-labs-hera

## The YAML authoring problem Hera targets

Argo Workflows definitions are YAML documents. Every template, argument, DAG dependency and resource request is a nested mapping, and there is no type checking between the file you write and the cluster that consumes it. Hera's README frames the project as the "go-to Python SDK to make Argo Workflows simple and intuitive", and the pitch is that you write the same workflow as Python objects instead. The audience is developers and research engineers who already have Python around their jobs: the classifiers in pyproject.toml list "Intended Audience :: Developers" and "Intended Audience :: Science/Research", and the recorded talks referenced in the README include LLM fine-tuning, gene therapy pipelines and rocket simulations. In each of those, the work itself is Python, so the workflow definition is the only part that leaves the language. Hera closes that gap. It does not replace Argo Workflows, and it does not replace Kubernetes. It replaces the hand-written YAML layer between your functions and the Argo controller.

## How a Python function becomes a workflow template

The mechanism is a decorator plus context managers. The README's at-a-glance example applies @script() to a plain function, which registers it as a reusable "Script template". The function body is what runs in the container; the decorator handles the packaging into a template definition. Orchestration then happens outside the function, inside a with Workflow(...) block, and inside that a with DAG(name=...) block. Tasks are created by calling the decorated function with a name and arguments, and ordering is expressed with the >> operator, as in A >> [B, C] >> D. That line is the dependency graph, and it is ordinary Python, so a list of tasks on the right-hand side fans out and the final task joins them. Nothing about the function body knows it is inside a DAG. The README calls this out directly: orchestration logic lives outside of business logic. The final step is submission. w.create() sends the workflow to the cluster. The generated models are not hand-written: the Makefile pulls the Argo Workflows OpenAPI spec (ARGO_WORKFLOWS_VERSION=4.0.5) and runs make codegen to regenerate models, services, examples and init files, with make check-codegen failing CI if the generated code drifts from the spec. That is the strongest structural signal in the repository about how the SDK tracks upstream Argo.

## Installing Hera and running a first workflow

Hera is on PyPI, and the README's installation table gives the command as pip install hera. It requires Python >=3.10,<4 per pyproject.toml. Three extras exist. hera[yaml] pulls in PyYAML for Workflow.to_yaml(), which the README ties to GitOps practices and easier debugging. hera[cli] adds Cappa and black for the experimental CLI that converts between YAML and Python source. hera[async-client] adds httpx for the async_* workflow functions through AsyncWorkflowsService.

```bash
pip install hera
```

Before any submission you need a reachable Argo Workflows server. The README states Hera requires one deployed to a Kubernetes cluster, and points at the Argo Workflows quick-start guide for deploying it. Hera assumes the server sits behind an authentication layer, so requests carry a Bearer token. The alternative the README names is port-forwarding the Argo server deployment and submitting to localhost:2746.

The README's authentication example uses the argo CLI as a token source, with the server port-forwarded:

```python
from hera.workflows import Workflow, Container
from hera.shared import global_config
from hera.auth import ArgoCLITokenGenerator

global_config.host = "http://localhost:2746"
global_config.token = ArgoCLITokenGenerator

with Workflow(generate_name="local-test-", entrypoint="c") as w:
    Container(name="c", image="docker/whalesay", command=["cowsay", "hello"])

w.create()
```

Setting global_config.token to the ArgoCLITokenGenerator class, rather than an instance, is how the README wires the CLI in as a token provider. Running this should submit a single-container workflow named with the local-test- prefix, and the container runs cowsay hello. The same w object can be rendered with to_yaml() if the yaml extra is installed, which is the practical way to inspect what will be sent before sending it. For the decorator-based DAG style shown earlier, the entrypoint is the DAG name and each task name must be unique within the workflow.

## Where Hera stops being the right tool

The dependency on a live Argo Workflows server is the first constraint, and it is stated plainly in the requirements. Hera is not a workflow engine. It builds and submits objects; execution, retries, pod scheduling and artifact handling belong to Argo. If you want to run a DAG on a laptop with no cluster, Hera adds a Kubernetes requirement you did not have.

The second constraint is the version coupling. The Makefile pins ARGO_WORKFLOWS_VERSION=4.0.5 for code generation, so the generated models track that spec. If your cluster runs a materially different Argo Workflows version, the fields Hera can express are the fields in that spec, and newer or older server fields may not have a Python counterpart. The README does not document a support matrix mapping Hera releases to Argo server versions, so that check is on you.

The third is the CLI. The README flags it in italics: the CLI is an experimental feature and subject to change. Building a GitOps pipeline around hera generate yaml means building on an interface the project reserves the right to alter. The Python API is the stable surface; the CLI is not.

Finally, authentication is assumed rather than solved. The README notes Hera assumes the Argo server sits behind an authentication layer. If your cluster exposes the server differently, you are working out the token path yourself.

## Hera against writing YAML by hand or using the Argo CLI

The alternative most teams actually weigh is plain YAML manifests submitted with kubectl or the argo CLI. The difference is where correctness is enforced. With YAML, a misspelled field or a wrong nesting level is caught by the server or not at all; the file is data and your editor may help, but nothing checks it against the schema before submission. With Hera, the workflow is constructed from generated pydantic models (pydantic >=2.0,<3.0 in pyproject.toml), so constructing an invalid object fails in Python before any request is made. That is the real trade: you gain a type system over the workflow definition and you pay for it with a Python runtime and a dependency on the SDK tracking the Argo spec.

The second alternative is the Argo CLI itself. It submits YAML; it does not give you a way to define a DAG in code. Hera's CLI extra goes the other direction, converting between YAML and Python source, which is useful for migrating existing manifests rather than authoring new ones. If your workflows are already generated by another templating system and are stable, Hera is an extra layer with no payoff. It earns its place when the workflow definition needs to share logic, types or constants with the Python code the workflow runs.

## Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-08. The release cadence visible in the release history is roughly quarterly: 6.0.0 on 2026-03-19, 7.0.0 on 2026-06-18, 7.1.0 on 2026-08-18. Two of the three most recent releases are major versions, which is worth reading carefully. Major bumps in a library like this usually mean the generated models or the public API moved with an Argo Workflows change, and the CHANGELOG.md at the repository root is where that would be spelled out. pyproject.toml lists two maintainers and the project sits under the argoproj-labs organisation, with GOVERNANCE.md, CONTRIBUTING.md, SECURITY.md and MEMBERS.md present at the top level. The Makefile shows the upgrade path for contributors rather than users: bump ARGO_WORKFLOWS_VERSION, run make codegen, and CI's check-codegen target fails if the generated files are not committed. For a user, the practical upgrade cost is that a major Hera release may require touching workflow definitions if the underlying Argo spec changed fields you use.

The licence is Apache-2.0, declared in both pyproject.toml and the LICENSE file. It is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your workflow code. That matters here because Hera is a client library you import into your own repository. This is a description of what the repository declares, not legal advice; if you redistribute Hera itself or bundle it into a product, read the licence text and your own counsel's guidance.

## Conclusion

Adopt Hera if you already run an Argo Workflows server and want workflow definitions in typed Python that share code with the rest of your repository; skip it if you have no Argo deployment to submit to, since the README states Hera requires one. Before committing, verify which Argo Workflows version your server runs against the 4.0.5 OpenAPI spec pinned in the Makefile, and confirm your authentication path (ArgoCLITokenGenerator or a port-forward to localhost:2746) works from where the code will actually execute.

## FAQ

### What is argoproj-labs/hera used for?

Hera is a Python SDK for constructing and submitting Argo Workflows. It turns Python functions into containerised templates and lets you define DAG ordering in Python, then submit the workflow to an Argo Workflows server with w.create().

### Is argoproj-labs/hera free to use?

Yes. The repository declares the Apache-2.0 licence in both pyproject.toml and the LICENSE file, and the package is published on PyPI as hera.

### What are the use cases for argoproj-labs/hera?

The README and its linked talks point at data science and research pipelines, including LLM fine-tuning and gene therapy workflows, plus general container orchestration on Kubernetes. The common thread is Python work that needs to run as ordered steps on a cluster.

### What are the key differences between ArgoCD and Argo Workflows?

Hera targets Argo Workflows, the workflow engine, not Argo CD, the GitOps deployment tool. The README states Hera requires an Argo Workflows server on a Kubernetes cluster, and none of the documented configuration keys relate to Argo CD.

## Sources

- [argoproj-labs/hera on GitHub](https://github.com/argoproj-labs/hera)
- [License: Apache-2.0](https://github.com/argoproj-labs/hera/blob/main/LICENSE)
- [Project website](https://hera.rtfd.io)
- [README](https://github.com/argoproj-labs/hera/blob/main/README.md)
- [Releases](https://github.com/argoproj-labs/hera/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/argoproj-labs-hera