Install & Compatibility
Where this runs
tested against v1.16.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.352s · 23.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.064s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
literals_pb2
✓ from flyteidl.core import literals_pb2
✗ import flyteidl.core.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.
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}")
Debug
Known issues
breakingThe 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.fixEnsure 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`.
affects: All versions, especially when migrating or working with different Flyte platform versions.
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.fixFor defining tasks, workflows, and interacting with the Flyte platform, prefer using `flytekit` (`pip install flytekit`) which builds upon `flyteidl`.
affects: All
gotchaThe `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.fixDo not modify files within the `flyteidl` package directly. If you need custom data structures, define your own Protobufs or Python classes outside this package.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flyteidl.service.external_plugin_service_pb2_grpc'
This error typically occurs due to version mismatches between `flyteidl` and `flytekit`, an incomplete installation of `flyteidl`, or the required submodule not being present in the Python environment of the execution container.
fixEnsure that `flyteidl` and `flytekit` are installed at compatible versions (refer to the Flyte compatibility matrix). If running tasks in a container, verify that all necessary modules are correctly packaged within your Docker image and that the Python path includes them. Reinstalling `flyteidl` and `flytekit` in a clean virtual environment can often resolve installation-related issues.
ImportError: cannot import name 'builder' from 'google.protobuf.internal'
This `ImportError` arises from a version conflict with the `protobuf` library. `flyteidl` and its dependencies (like `flytekit`) require a specific range of `protobuf` versions, while another installed library might be forcing an incompatible version.
fixPin your `protobuf` version to a range compatible with your `flyteidl` and `flytekit` installation, often `protobuf<4.0.0` or `protobuf>=3.1.0, <4.0.0` for common `flyteidl` versions. Consult the official Flyte documentation or `pyproject.toml` of `flytekit` for the precise `protobuf` version requirements for your specific Flyte ecosystem versions.
AttributeError: 'Output' object has no attribute 'ref'
This `AttributeError` often indicates an attempt to access an internal or deprecated attribute ('ref') on a Flyte object, such as a task output, which might have been removed or renamed in newer `flytekit` or `flyteidl` versions due to API changes.
fixUpdate your `flytekit` and `flyteidl` libraries to their latest compatible versions. If the error persists, consult the Flyte documentation for the correct way to access task outputs or object properties for your specific Flyte version, avoiding direct access to internal attributes.
ModuleNotFoundError: No module named 'mymodule'
When encountered within a Flyte task's execution in a container, this error signifies that a custom Python module ('mymodule') required by your task is not available in the container image. This can be due to an improperly configured Dockerfile, missing `__init__.py` files, or an incorrect Python path.
fixEnsure your Dockerfile correctly includes and installs all project dependencies and custom modules into the container image. Verify that your project structure is recognized as a Python package (e.g., by including `__init__.py` files in directories containing modules) and that these paths are accessible in the container's Python environment.
Upgrade
Version history
1.16.8latest on PyPI · released Jul 9, 2026
Audit
Dependencies
No dependency data recorded yet.