Run context

Every Flyte run has a run context: a set of invocation-time parameters that control where the run executes, where its outputs are stored, how caching behaves, and more.

There are two sides to run context:

• Write side: flyte.with_runcontext() sets run parameters before the run starts (programmatic) or via CLI flags.
• Read side: flyte.ctx() accesses run parameters inside a running task.

Configuring a run with flyte.with_runcontext()

flyte.with_runcontext() returns a runner object. Call .run(task, ...) on it to start the run with the specified context:

import flyte

env = flyte.TaskEnvironment("run-context-example")

@env.task
async def process(n: int) -> int:
    return n * 2

@env.task
async def root() -> int:
    return await process(21)

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        name="my-run",
        project="my-project",
        domain="development",
    ).run(root)

All parameters are optional. Unset parameters inherit from the configuration file (config.yaml) or system defaults.

Execution target

Storage

For the difference between what raw_data_path controls (offloaded values) and what stays at the deployment-configured location (inputs.pb, outputs.pb, Decks) or in the control plane database, see Where your data lives.

To direct all task outputs to a specific bucket for a run:

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        # Store all task outputs in a dedicated S3 prefix for this run
        raw_data_path="s3://my-bucket/runs/experiment-42/",
    ).run(root)

The equivalent CLI flag is --raw-data-path. See Run command options for CLI usage.

Caching

Identity and resources

Labels tag a run with arbitrary key=value metadata so you can find and group related runs later, and are also propagated to the run’s task pods as Kubernetes labels (available for cluster-level monitoring, routing, or policies). Set them programmatically with with_runcontext(labels={...}), or from the CLI with the repeatable --label flag:

flyte run --label team=ml --label env=prod my_example.py main

To list and filter runs by their labels, see Filtering runs by label.

Logging

For setting the logging level (including via environment variables), the framework-vs-user logger split, and capturing third-party library logs as JSON with reset_root_logger, see Logging.

Code bundling

Context propagation

Reading context inside a task with flyte.ctx()

Inside a running task, flyte.ctx() returns a TaskContext object with information about the current execution. Outside of a task, it returns None.

@env.task
async def inspect_context() -> str:
    ctx = flyte.ctx()
    action = ctx.action
    return (
        f"run={action.run_name}, "
        f"action={action.name}, "
        f"mode={ctx.mode}, "
        f"in_cluster={ctx.is_in_cluster()}"
    )

TaskContext fields

ActionID fields

The ctx.action object identifies this specific task invocation:

Naming external resources

ctx.action.run_name is useful for tying external tool runs (experiment trackers, dashboards) to the corresponding Flyte run:

import wandb  # type: ignore[import]

@env.task
async def train_model(epochs: int) -> float:
    ctx = flyte.ctx()
    # Use run_name to tie the W&B run to this Flyte run
    run = wandb.init(
        project="my-project",
        name=ctx.action.run_name,
        config={"epochs": epochs},
    )
    # ... training logic ...
    loss = 0.42
    run.log({"loss": loss})
    run.finish()
    return loss

This ensures that when you look up a run in Weights & Biases (or any other tool), its name matches what you see in the Flyte UI.