Install & Compatibility
Where this runs
tested against v1.83.1 · 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.522s · 61.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 0.078s · 60MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DiscoveryRequest
✓ from envoy.service.discovery.v3 import discovery_pb2
Common xDS messages are typically found under `envoy.<config|service>.<category>.v3` subpackages.
Cluster
✓ from envoy.config.cluster.v3 import cluster_pb2
TypedStruct
✓ from xds.type.v3 import typed_struct_pb2
✗ from udpa.type.v1 import typed_struct_pb2
Older versions of some xDS types (like TypedStruct) were under the `udpa` package and have since moved to `xds` as part of API generalization.
Demonstrates importing a core xDS message (`DiscoveryRequest`) and instantiating it. This package provides the generated message classes for use in xDS clients or servers.
from envoy.service.discovery.v3 import discovery_pb2
# Create a simple DiscoveryRequest message
request = discovery_pb2.DiscoveryRequest(
version_info='1.0.0',
node=None, # In a real scenario, this would be a Node message
resource_names=['my-cluster'],
type_url='type.googleapis.com/envoy.config.cluster.v3.Cluster',
response_nonce='some-nonce'
)
print(f"Created DiscoveryRequest: {request}")
# Accessing fields
print(f"Requested resource names: {request.resource_names}")
Debug
Known issues
breakingSome xDS proto types, notably `TypedStruct`, have migrated from the `udpa.type.v1` package to `xds.type.v3`. This changes their Python import paths (e.g., from `udpa.type.v1.typed_struct_pb2` to `xds.type.v3.typed_struct_pb2`). Consumers of specific xDS types should verify their imports, especially when upgrading.fixUpdate import statements to reflect the new `xds.*` package paths (e.g., `from xds.type.v3 import typed_struct_pb2`). Refer to the `cncf/xds` repository for current proto locations.
affects: <=1.x.x (exact range varies by specific proto migration)
gotchaThe xDS APIs are constantly evolving, and some features, or even entire protos, are marked as 'work-in-progress'. These entities are subject to breaking changes without prior notice.fixReview the official xDS API documentation (e.g., on `envoyproxy.io` or `cncf/xds` GitHub) for `work_in_progress` annotations on specific messages or fields if encountering unexpected changes or instability.
affects: All versions
gotchaxDS utilizes two primary transport protocols: State-of-the-World (SotW) and Delta xDS. These protocols use different request/response protos (`DiscoveryRequest`/`DiscoveryResponse` for SotW vs. `DeltaDiscoveryRequest`/`DeltaDiscoveryResponse` for Delta xDS) and are fundamentally incompatible. Mixing them will lead to failures.fixEnsure that both the xDS client and server are configured to use the same xDS transport protocol variant (either SotW or Delta) and the corresponding proto messages.
affects: All versions supporting both SotW and Delta xDS
gotchaProtoc-Gen-Validate (PGV) annotations on xDS protos can evolve, making validation rules less strict over time without being considered a breaking API change. This can lead to situations where a control plane expects stricter validation than a client built with older protos, or vice-versa, causing resource rejection mismatches.fixRegularly update `xds-protos` to align with the control plane's deployed xDS API version. Implement robust error handling for resource rejections and consider logging validation discrepancies for debugging.
affects: All versions
gotchaThis package consists of generated Python protobuf code. It has a runtime dependency on the `protobuf` Python package. Incompatibilities can arise if the `xds-protos` package is generated with a `protoc` version that is significantly newer or older than the `protobuf` runtime library installed in the environment.fixEnsure that the `protobuf` runtime package version is compatible with the `protoc` version used to generate `xds-protos`. If encountering issues, try upgrading `protobuf` (e.g., `pip install --upgrade protobuf`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xds-protos'
Python import statements require package names to use underscores (_) instead of hyphens (-) for packages installed via pip.
fixUse the correct Python package name `xds_protos` in your import statement: `import xds_protos` or `from xds_protos...`
ModuleNotFoundError: No module named 'xds_protos.envoy.api.v2.core'
The xDS API has transitioned many core types from legacy `v2` paths (e.g., `envoy.api.v2.core`) to current `v3` paths (e.g., `envoy.config.core.v3`).
fixUpdate the import statement to use the correct `v3` path. For example, replace `from xds_protos.envoy.api.v2.core import base_pb2` with `from xds_protos.envoy.config.core.v3 import base_pb2`.
AttributeError: 'DiscoveryRequest' object has no attribute 'nonce'
The specific field name `nonce` is incorrect for the `DiscoveryRequest` message in the xDS API; the correct field is `response_nonce`.
fixUse the correct field name `response_nonce` to access the nonce value: `request.response_nonce` where `request` is an instance of `DiscoveryRequest`.
Upgrade
Version history
1.83.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
protobufrequiredRequired at runtime for the protobuf messages generated by this library.