{"id":5230,"library":"flyteidl","title":"Flyte IDL","description":"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).","status":"active","version":"1.16.6","language":"en","source_language":"en","source_url":"https://github.com/flyteorg/flyte","tags":["flyte","idl","workflow","orchestration","protobuf","data-pipeline"],"install":[{"cmd":"pip install flyteidl","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"Commonly imported directly from the subpackage for clarity and brevity.","wrong":"import flyteidl.core.literals_pb2","symbol":"literals_pb2","correct":"from flyteidl.core import literals_pb2"},{"note":"For definitions related to the Flyte Admin service and entities.","symbol":"admin_pb2","correct":"from flyteidl.admin import admin_pb2"},{"note":"For core workflow structure definitions.","symbol":"workflow_pb2","correct":"from flyteidl.core import workflow_pb2"}],"quickstart":{"code":"from flyteidl.core import literals_pb2, workflow_pb2\n\n# Create a simple Scalar literal with a primitive integer value\ninteger_scalar = literals_pb2.Scalar(\n    primitive=literals_pb2.Primitive(integer=42)\n)\nprint(f\"Integer Scalar value: {integer_scalar.primitive.integer}\")\n\n# Create a simple Scalar literal with a string value\nstring_scalar = literals_pb2.Scalar(\n    primitive=literals_pb2.Primitive(string_value=\"hello flyte!\")\n)\nprint(f\"String Scalar value: {string_scalar.primitive.string_value}\")\n\n# Demonstrate creating a more complex structure, like a NodeOutput binding\nnode_output_binding = workflow_pb2.NodeOutput(\n    var=\"my_node_output\",\n    sdk_binding=workflow_pb2.BindingData(\n        scalar=literals_pb2.Scalar(\n            primitive=literals_pb2.Primitive(float_value=3.14)\n        )\n    )\n)\n\nprint(f\"Node Output Variable: {node_output_binding.var}\")\nprint(f\"Bound Float Value: {node_output_binding.sdk_binding.scalar.primitive.float_value}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions, especially when migrating or working with different Flyte platform versions."},{"fix":"For defining tasks, workflows, and interacting with the Flyte platform, prefer using `flytekit` (`pip install flytekit`) which builds upon `flyteidl`.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}