Flyte IDL

1.16.6 · active · verified Mon Apr 13

flyteidl is the Interface Definition Language (IDL) for the Flyte platform, providing Python bindings for the core protobuf messages and services. It defines the data structures and RPC interfaces used throughout the Flyte ecosystem, including task definitions, workflow structures, and execution states. As of its latest v1.x release, it is at version 1.16.6. The library's release cadence is tied to the broader Flyte platform releases, with active development supporting both a v1.x and a separate v2.x stream (flyteidl2).

Warnings

breaking The Flyte platform has two major versions with distinct IDL packages. `flyteidl` (this package) corresponds to Flyte v1.x. Flyte v2.x uses a separate package, `flyteidl2`. Mixing these packages or using `flyteidl` with a Flyte v2.x backend/`flytekit` version will result in incompatibility issues and errors.
Fix: Ensure that your installed `flyteidl` or `flyteidl2` package aligns with the version of the Flyte platform and `flytekit` you are using. For Flyte v1.x, use `flyteidl`; for Flyte v2.x, use `flyteidl2`.
gotcha `flyteidl` is primarily a low-level, internal dependency for `flytekit` and other Flyte components. While direct usage is possible for advanced scenarios (e.g., custom integrations or direct API calls), most users should interact with Flyte via the higher-level abstractions provided by `flytekit` to ensure type safety, ease of use, and forward compatibility.
Fix: For defining tasks, workflows, and interacting with the Flyte platform, prefer using `flytekit` (`pip install flytekit`) which builds upon `flyteidl`.
gotcha The `flyteidl` package consists of auto-generated Protobuf code. Modifying these generated files directly is strongly discouraged as any changes will be overwritten during package updates, potentially leading to build failures or runtime inconsistencies.
Fix: Do not modify files within the `flyteidl` package directly. If you need custom data structures, define your own Protobufs or Python classes outside this package.

Install

pip install flyteidl Install latest stable version

Imports

literals_pb2
```
from flyteidl.core import literals_pb2
```
Commonly imported directly from the subpackage for clarity and brevity.
admin_pb2
```
from flyteidl.admin import admin_pb2
```
For definitions related to the Flyte Admin service and entities.
workflow_pb2
```
from flyteidl.core import workflow_pb2
```
For core workflow structure definitions.

Quickstart

This quickstart demonstrates how to import and instantiate basic protobuf messages from `flyteidl.core` such as `Scalar` and `NodeOutput`. `flyteidl` provides the raw, generated Python classes for Flyte's internal data structures.

from flyteidl.core import literals_pb2, workflow_pb2

# Create a simple Scalar literal with a primitive integer value
integer_scalar = literals_pb2.Scalar(
    primitive=literals_pb2.Primitive(integer=42)
)
print(f"Integer Scalar value: {integer_scalar.primitive.integer}")

# Create a simple Scalar literal with a string value
string_scalar = literals_pb2.Scalar(
    primitive=literals_pb2.Primitive(string_value="hello flyte!")
)
print(f"String Scalar value: {string_scalar.primitive.string_value}")

# Demonstrate creating a more complex structure, like a NodeOutput binding
node_output_binding = workflow_pb2.NodeOutput(
    var="my_node_output",
    sdk_binding=workflow_pb2.BindingData(
        scalar=literals_pb2.Scalar(
            primitive=literals_pb2.Primitive(float_value=3.14)
        )
    )
)

print(f"Node Output Variable: {node_output_binding.var}")
print(f"Bound Float Value: {node_output_binding.sdk_binding.scalar.primitive.float_value}")

view raw JSON →