Install & Compatibility
Where this runs
tested against v7.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 2.676s · 37.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.2s · import 2.449s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workflow
✓ from hera.workflows import Workflow
script
✓ from hera.workflows import script
DAG
✓ from hera.workflows import DAG
Steps
✓ from hera.workflows import Steps
global_config
✓ from hera.shared import global_config
✗ from hera.workflow_service import WorkflowService (deprecated pattern)
Configuration is now managed via `hera.shared.global_config` for broader applicability, rather than instantiating `WorkflowService` directly for host/token setup.
This quickstart demonstrates how to define a DAG (Directed Acyclic Graph) workflow using Hera, where tasks 'B' and 'C' run in parallel after 'A' completes, and 'D' runs after both 'B' and 'C' are finished. The `echo` function is converted into an Argo script template using the `@script` decorator. The workflow is then submitted to an Argo Workflows server configured via environment variables or a default local endpoint.
import os
from hera.workflows import DAG, Workflow, script
from hera.shared import global_config
# Configure Hera to connect to your Argo Workflows server
# Set ARGO_SERVER_HOST and ARGO_SERVER_TOKEN environment variables
# For local testing, ensure Argo Server is port-forwarded (e.g., kubectl -n argo port-forward service/argo-server 2746:2746)
global_config.host = os.environ.get("ARGO_SERVER_HOST", "http://localhost:2746")
global_config.token = os.environ.get("ARGO_SERVER_TOKEN", "") # Use actual token if required
@script(image="python:3.11")
def echo(message: str):
"""A simple Python function to echo a message."""
print(message)
with Workflow(
generate_name="hera-dag-diamond-",
entrypoint="diamond",
namespace="argo", # Ensure this matches your Argo Workflows namespace
labels={
"example": "true",
"sdk": "hera",
}
) as w:
with DAG(name="diamond"):
A = echo(name="A", arguments={"message": "Task A"})
B = echo(name="B", arguments={"message": "Task B"})
C = echo(name="C", arguments={"message": "Task C"})
D = echo(name="D", arguments={"message": "Task D"})
A >> [B, C] >> D
# Submit the workflow
try:
submitted_workflow = w.create()
print(f"Workflow '{submitted_workflow.metadata.name}' submitted successfully.")
print(f"Access UI at {global_config.host}/workflows/{submitted_workflow.metadata.namespace}/{submitted_workflow.metadata.name}")
except Exception as e:
print(f"Error submitting workflow: {e}")
print("Please ensure your Argo Workflows server is running and accessible, and ARGO_SERVER_HOST/TOKEN are configured correctly.")
hera --version
Debug
Known issues
breakingThe experimental decorator feature for `DAG`, `Steps`, `Container`, and `script` (introduced in v5.16) has been removed in v6.0.0. This means users should revert to the context manager pattern or the standard `@script()` decorator if they were using the `Workflow.dag()` or `Workflow.steps()` decorators.fixMigrate code using `Workflow.dag()`, `Workflow.steps()`, etc., decorators back to using context managers (e.g., `with DAG(...)`) or standard `@script()` for functions. The base `@script()` decorator remains supported.
affects: >=6.0.0
breakingHera v6.0.0 migrates core Hera classes to Python dataclasses and uses Pydantic v2 API models internally where Pydantic is still needed, removing support for Pydantic v1. If your custom script functions relied on Hera's internal Pydantic v1 models or if your project mixes Hera with Pydantic v1 models, you must upgrade your Pydantic dependency to v2 and address any compatibility issues.fixUpgrade Pydantic to v2 across your project. Review Pydantic's official migration guide for v1 to v2 breaking changes. Hera's internal models are now dataclasses, impacting direct interaction with `hera.workflows.models` classes.
affects: >=6.0.0
breakingHera v5.27.0 dropped support for Python 3.9. Users on Python 3.9 will need to upgrade their Python environment to 3.10 or newer to use Hera versions 5.27.0 and later.fixUpgrade your Python environment to version 3.10 or higher. Python 3.9 is also End-of-Life upstream, making an upgrade advisable regardless.
affects: >=5.27.0
gotchaHera requires an active Argo Workflows server in a Kubernetes cluster for workflow submission. It does not run workflows locally or manage Argo deployments. Proper authentication (e.g., Bearer token) and server accessibility (e.g., port-forwarding) must be configured.fixEnsure an Argo Workflows server is deployed and accessible. Configure `hera.shared.global_config.host` and `global_config.token` with the correct server address and authentication token, or ensure necessary port-forwarding is active for local development.
affects: All versions
gotchaThe Python package name for Hera changed from `hera-workflows` to `hera` for versions 5.0.0 and above. Attempting to install `hera-workflows` for newer Hera versions will result in an outdated installation.fixFor Hera versions 5.0.0 and later, use `pip install hera`. If you need to install versions prior to 5.0.0, use `pip install hera-workflows`.
affects: <5.0.0 (old name), >=5.0.0 (new name)
gotchaFunctions decorated with `@script()` are executed as containerized templates on Argo. This means the Docker image specified in the decorator (or default global image) must contain the Python environment and all dependencies required by the decorated function. Local imports and non-standard libraries need to be bundled into the image.fixSpecify a Docker image in the `@script(image="...")` decorator that includes all necessary Python dependencies (e.g., `numpy`, custom modules) for your function. Alternatively, build and use a custom Docker image from your project's codebase.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hera'
This error occurs when the 'hera' package is not installed in your Python environment, or if you are trying to import it using an incorrect name. Prior to version 5.0.0, the package was named 'hera-workflows'.
fixEnsure you have the correct package installed for your Hera version. For Hera v5.0.0 and later, use `pip install hera`. If you are using an older version (pre-5.0.0), use `pip install hera-workflows`.
argo.workflows.client.exceptions.ApiException: (401) Reason: Unauthorized
This error indicates that Hera is unable to authenticate with the Argo Workflows server. This is commonly due to an incorrect Argo Server host, a missing or invalid authentication token, or insufficient Kubernetes Role-Based Access Control (RBAC) permissions for the service account Hera is using.
fixVerify the `host` and `token` provided to `WorkflowService` or `global_config`. Ensure the Argo Workflows server is accessible, the token is valid, and the associated Kubernetes Service Account has the necessary RBAC permissions to create and manage workflows in the target namespace. For local testing, port-forwarding to `localhost:2746` can often bypass some authentication complexities.
AttributeError: 'Steps' object has no attribute 'templates'
This error typically occurs when attempting to define or instantiate `Steps` (or other workflow building blocks like `Tasks`) outside the proper context of a `Workflow` or `DAG` object, where they are expected to be nested using Python's `with` statement. Hera requires these components to be part of an active workflow context to correctly build the Argo YAML.
fixEnsure that `Steps` and `Task` definitions are always placed within the context manager of a `Workflow` or `DAG`. For example, use `with Workflow(...) as wf: with Steps(...) as steps: ...` or `with Workflow(...) as wf: with DAG(...) as dag: ...` to properly associate the components.
TypeError: issubclass() arg 1 must be a class
This `TypeError` often arises within Hera's runner when it attempts to introspect types of parameters passed to `@script` decorated functions, particularly with complex type hints (e.g., `Optional[str]`, `List[PydanticModel]`) or when `get_args` from the `typing` module returns something that is not a class, leading to an invalid argument for `issubclass`. This can be a subtle issue related to how types are resolved or passed.
fixReview the type hints of parameters in your `@script` decorated functions. Ensure they are correctly specified and compatible with Python's `typing` module and Hera's type introspection. If using complex types or Pydantic models, verify Hera's compatibility with the specific Pydantic version and consider simplifying type hints or ensuring all arguments correctly resolve to class types. Sometimes, simplifying generics or providing explicit class types can resolve the issue.
Upgrade
Version history
7.1.0latest on PyPI · released Aug 18, 2026
Audit
Dependencies
argo-workflowsrequiredHera is an SDK for Argo Workflows and requires an Argo server to be deployed and configured in a Kubernetes cluster.
PyYAMLoptionalRequired for YAML output functionality.
pydanticrequiredWhile core Hera models now use dataclasses, Pydantic (v2) is still used internally for some auto-generated models and can be used within script template functions for type validation.