Run locally

Flyte runs locally with no cluster or Docker needed. Install the SDK, write tasks, and run them on your machine. When you’re ready to scale, drop the --local flag and the same code runs on a remote cluster with GPUs.

Getting started

If you haven’t already, install the SDK and configure local persistence as described in the Quickstart.

Running tasks locally

The --local flag tells Flyte to execute a task in your local Python environment rather than on a remote cluster. Add --tui to launch the interactive Terminal UI for real-time monitoring.

Basic local execution:

flyte run --local hello.py main

With the interactive TUI:

flyte run --local --tui hello.py main

You can also run tasks programmatically using the Python SDK with flyte.run(). See Run and deploy tasks for details.

Two ways to run a task

There are two distinct ways to run a task, and it’s easy to confuse them when you’re new. They differ in who calls flyte.run().

As a script: python hello.py

You call flyte.run() yourself, from inside an if __name__ == "__main__": block, and execute the file with plain Python:

# hello.py
import flyte

env = flyte.TaskEnvironment(name="hello_env")

@env.task
def main(x_list: list[int] = list(range(10))) -> float:
    return sum(x_list) / len(x_list)

if __name__ == "__main__":
    flyte.init_from_config()       # load your local config (.flyte/config.yaml)
    run = flyte.run(main)          # call the task; pass inputs as keyword args
    print(run.name)
    run.wait()

Then run the file as an ordinary Python script:

python hello.py

Because your code decides which task runs and with what inputs, you pass inputs directly as arguments to flyte.run() — for example flyte.run(main, x_list=[1, 2, 3]). Use flyte.run.aio(...) from within async code.

Via the CLI: flyte run

The flyte run CLI does the calling for you. You don’t need a __main__ block — instead you name the file and the task on the command line, and the CLI invokes it:

flyte run --local hello.py main

The task’s parameters become CLI options. Each task input maps to a --<name> flag (run flyte run --local hello.py main --help to see them, with their defaults). For example, to override x_list:

flyte run --local hello.py main --x-list '[1, 2, 3]'

Terminal UI

The TUI is an interactive split-screen dashboard. Task tree on the left, details and logs on the right.

flyte run --local hello.py main

What you see:

• Task tree with live status: ● running, ✓ done, ✗ failed
• Cache indicators: $ cache hit, ~ cache enabled but missed
• Live logs: print() output streams in real time
• Details panel: inputs, outputs, timing, report paths
• Traced sub-tasks: child nodes for @flyte.trace decorated functions

Keyboard shortcuts:

Exploring past runs

If you created a config file via flyte create config --local-persistence, Flyte persists the inputs and outputs of every task run locally, so you can always go back and inspect what a task received and produced. Launch the TUI on its own to browse past runs, compare inputs and outputs, and review reports:

flyte start tui

What works locally

Most Flyte features work in both local and remote execution. The table below summarizes how each feature behaves locally.

Local to devbox/remote

The same code runs in both environments. Here’s what changes:

The TaskEnvironment is the bridge. Locally, image and resource settings are ignored. On the cluster, Flyte builds containers and allocates compute from the same definition.

Next steps