Skip to main content
This guide walks you through running your first Flyte workflow — from a local Python environment to a remote cluster.

​
Prerequisites

  • Python 3.8 or higher
  • pip available in your environment

​
Run your first workflow locally

1

Install flytekit

Install Flyte’s Python SDK:
pip install -U flytekit
This installs both the flytekit Python package and the pyflyte CLI tool.
2

Write a Hello World workflow

Create a file called example.py with the following content:
example.py
from flytekit import task, workflow


@task
def say_hello(name: str) -> str:
    return f"Hello, {name}!"


@workflow
def hello_world_wf(name: str = "world") -> str:
    res = say_hello(name=name)
    return res


if __name__ == "__main__":
    print(f"Running wf() {hello_world_wf(name='passengers')}")
The @task decorator marks a regular Python function as a Flyte task. The @workflow decorator marks a function as a Flyte workflow that composes those tasks.
You can also scaffold this project using pyflyte init:
pyflyte init --template hello-world hello-world
cd hello-world
3

Run it locally with pyflyte run

Execute the workflow in your local Python environment:
pyflyte run example.py hello_world_wf
The initial arguments of pyflyte run take the form path/to/script.py <task_or_workflow_name>. You can pass inputs as flags:
pyflyte run example.py hello_world_wf --name Ada
You should see output like:
Running hello_world_wf() Hello, Ada!
Tasks and workflows must always be invoked with keyword arguments. Positional arguments are not supported.

​
Run on a local Flyte cluster

The flytectl demo start command spins up a self-contained Flyte cluster running as a Docker container. This lets you test the full Flyte experience — including the FlyteConsole UI — without any cloud infrastructure.
1

Install flytectl

Install the Flyte CLI:
brew install flyteorg/homebrew-tap/flytectl
2

Start the local demo cluster

Start a local Flyte cluster in a Docker container:
flytectl demo start
This command pulls the Flyte sandbox image and starts FlyteAdmin, FlytePropeller, and FlyteConsole. The first run takes a few minutes to download images.Once started, you can access FlyteConsole at http://localhost:30080/console.
Docker must be installed and running before you run flytectl demo start.
3

Run the workflow on the remote cluster

Add the --remote flag to execute your workflow on the local demo cluster instead of your local Python interpreter:
pyflyte run --remote example.py hello_world_wf --name world
Flyte registers the workflow, creates an execution, and prints a URL where you can monitor progress in FlyteConsole.

​
The @task and @workflow decorators

The two core decorators you use every day in Flyte are @task and @workflow. 
from flytekit import task, workflow


@task
def say_hello(name: str) -> str:
    return f"Hello, {name}!"


@workflow
def hello_world_wf(name: str = "world") -> str:
    res = say_hello(name=name)
    return res
DecoratorWhat it does
@taskMarks a Python function as a Flyte task. When run on a cluster, each task executes in its own isolated container on a Kubernetes Pod.
@workflowMarks a function as a Flyte workflow. The workflow body is a DSL for building a DAG — it composes tasks but does not run computation itself.
Workflow functions are compiled into execution graphs at registration time. The inputs and outputs of tasks within a workflow are promises (lazy references), not actual Python values. This is why you cannot use regular Python control flow like if/else on task outputs inside a workflow.

​
Using FlyteRemote to execute workflows programmatically

For larger projects where you have registered workflows to a cluster, use the FlyteRemote client instead of pyflyte run: 
from flytekit.configuration import Config
from flytekit.remote import FlyteRemote

remote = FlyteRemote(
    config=Config.auto(),
    default_project="flytesnacks",
    default_domain="development",
)

# Execute a locally imported workflow
from workflows.example import hello_world_wf

execution = remote.execute(
    hello_world_wf,
    inputs={"name": "world"},
)

print(f"Execution url: {remote.generate_console_url(execution)}")

​
Next steps

Key Concepts

Understand tasks, workflows, launch plans, and projects in depth.

Tasks

Learn about task types, resource requests, caching, retries, and plugins.

Workflows

Learn how workflows build DAGs, handle promises, and support subworkflows.

User Guide

Go deeper into the Flyte SDK with data types, advanced composition, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us