Install & Compatibility
Where this runs
tested against v0.31.0 · 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.562s · 21.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.070s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
proto
✓ from substrait import proto
The primary module for accessing Substrait Plan classes.
This example demonstrates how to programmatically construct a simple Substrait Plan using the `substrait.proto` module, serialize it to bytes, and shows how to conceptually load plans from bytes or JSON strings. This plan represents a 'SELECT first_name FROM people' query with a defined schema for the 'people' table.
from substrait import proto
# Example: Create a simple Substrait Plan equivalent to SELECT first_name FROM person
plan = proto.Plan(
relations=[
proto.PlanRel(
root=proto.RelRoot(
names=["first_name"],
input=proto.Rel(
read=proto.ReadRel(
named_table=proto.ReadRel.NamedTable(names=["people"]),
base_schema=proto.NamedStruct(
names=["first_name", "surname"],
struct=proto.Type.Struct(
types=[
proto.Type(string=proto.Type.String(nullability=proto.Type.Nullability.NULLABILITY_REQUIRED)),
proto.Type(string=proto.Type.String(nullability=proto.Type.Nullability.NULLABILITY_REQUIRED))
]
)
)
)
)
)
)
]
)
print(plan)
serialized_plan = plan.SerializeToString()
print(f"Serialized plan length: {len(serialized_plan)} bytes")
# To consume a plan from bytes:
# loaded_plan = proto.Plan()
# loaded_plan.ParseFromString(serialized_plan)
# print(loaded_plan)
# To load a plan from JSON (assuming you have a JSON string 'json_plan_str'):
# from google.protobuf import json_format
# json_plan_str = "{... your JSON plan ...}"
# loaded_plan_from_json = json_format.Parse(json_plan_str, proto.Plan())
# print(loaded_plan_from_json)
Debug
Known issues
gotchaThe `substrait` Python package is explicitly marked as 'experimental' and 'still under development'. This means its API and behavior may change frequently without adhering strictly to semantic versioning for minor releases, potentially causing unexpected breakages.fixAlways pin to exact versions (`substrait==X.Y.Z`) in production environments and regularly review release notes for updates. Be prepared for breaking changes.
affects: All 0.x.x versions
gotchaThis library is *not* an execution engine for Substrait plans. Its primary purpose is to provide a Python interface for *producing* and *consuming* Substrait plans, which are then meant to be executed by external Substrait-compliant data compute engines (e.g., DataFusion, DuckDB).fixDo not expect `substrait` to execute queries directly. Integrate it with a compatible Substrait consumer for execution.
affects: All versions
breakingThe underlying Substrait specification itself undergoes breaking changes, and the Python bindings are tightly coupled to this specification. For example, a significant URI to URN migration occurred in 2025 across the Substrait ecosystem. Such changes in the spec will lead to corresponding breaking changes in the Python library.fixMonitor the official Substrait specification's breaking change policy and changelogs, as well as the `substrait-python` release notes. Update dependencies and code to align with the latest spec and library versions.
affects: Potentially all 0.x.x versions, specifically changes around 2025 for URI to URN migration.
gotchaCompatibility with other Substrait tools (producers, consumers, validators) can be complex due to the evolving nature of the Substrait specification. Different versions of consumers or validators may only support specific ranges of the Substrait spec, which the Python library reflects.fixEnsure that all components in your Substrait pipeline (Python library, external producers/consumers, validators) are compatible with a consistent Substrait specification version. Refer to the `substrait-validator` documentation for version compatibility matrices if using the validator.
affects: All 0.x.x versions
Upgrade
Version history
0.31.0latest on PyPI · released Aug 16, 2026
Audit
Dependencies
pythonrequiredRuntime environment requirement