Namespaces

Declare, register, and target workflow namespaces from your Python code and the CLI to isolate workflows by team, service, or environment.

This page covers the developer-side perspective on namespaces. For operator-side setup (isolation, quotas, RBAC), see Operate → Multi-tenancy → namespaces.

What namespaces do

A workflow’s full identity in Flux is (namespace, name). Two workflows can share the same short name as long as they live in different namespaces. Namespaces map to teams, services, or deployment environments — for example, billing, reporting, data-ingestion, or staging.

Workflows without an explicit namespace land in default. For single-team projects that’s often enough; once you have multiple teams or need to isolate staging from production, namespaces give you a clean boundary without additional infrastructure.

Declaring a namespace in code

Pass namespace to workflow.with_options:

from flux import workflow, ExecutionContext

@workflow.with_options(namespace="billing")
async def invoice(ctx: ExecutionContext[str]):
    return f"Invoice for {ctx.input}"

The namespace is stored on the workflow object and sent to the server at registration time. You can inspect it:

print(invoice.namespace)        # billing
print(invoice.qualified_name)   # billing/invoice

Without a namespace, qualified_name uses default:

@workflow
async def generic_task(ctx: ExecutionContext[str]):
    return ctx.input

print(generic_task.namespace)       # default
print(generic_task.qualified_name)  # default/generic_task

Namespace naming rules

Names like data-ingestion, team_alpha, and prod-v2 are valid. Names like DataIngestion or -staging are not.

Combining namespace with other options

namespace composes freely with name, affinity, requests, and other with_options parameters:

from flux import workflow, ExecutionContext
from flux.domain.resource_request import ResourceRequest

@workflow.with_options(
    namespace="reporting",
    name="monthly_report",
)
async def monthly_report_fn(ctx: ExecutionContext[str]):
    return f"Report: {ctx.input}"

# Namespace + affinity + resource requests
@workflow.with_options(
    namespace="ml",
    affinity={"role": "training", "gpu": "a100"},
    requests=ResourceRequest(gpu=1, memory="16Gi"),
)
async def fine_tune(ctx: ExecutionContext[str]):
    ...

When you give a workflow an explicit name, the qualified name is namespace/name rather than namespace/function_name.

Registering a namespaced workflow

Registration works the same way regardless of namespace — you pass the file to flux workflow register. The namespace is embedded in the workflow definition, not in the CLI command:

flux workflow register billing_workflows.py

After registration, the server stores each workflow under its qualified name (billing/invoice in this case).

Targeting a namespaced workflow from the CLI

The CLI, HTTP API, MCP server, and Python client all accept qualified names in the form namespace/workflow_name:

# Run a namespaced workflow
flux workflow run billing/invoice '"acme-corp"'

# Show a specific namespaced workflow
flux workflow show billing/invoice

# Check execution status — the execution ID is returned by flux workflow run
flux workflow status <execution-id>

Bare names (without a /) are treated as default/name for backward compatibility:

# These two commands are equivalent
flux workflow run generic_task '"input"'
flux workflow run default/generic_task '"input"'

Listing namespaces

To see all namespaces that have at least one registered workflow:

flux workflow list-namespaces

To filter the workflow list to a single namespace:

flux workflow list --namespace billing

The --namespace flag accepts a namespace name and returns only workflows in that namespace.

Filtering by namespace

To see only your team’s workflows, combine --namespace with --format json to pipe the output to other tools:

flux workflow list --namespace billing --format json | jq '.[].name'

What workers see

Workers are not scoped to a namespace. A worker started with flux start worker receives executions from any namespace, based on affinity and resource matching alone. Namespace isolation is enforced at the server level: the server decides which executions to dispatch and to whom. In your workflow code, the namespace is an attribute on the workflow definition; it has no effect on how the workflow body executes.

What’s next