Install & Compatibility
Where this runs
tested against v0.8.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.000s · 68.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.0s · import 0.000s · 65MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Listener
✓ from envoy_data_plane import Listener
✗ from envoy_data_plane import Listener
This quickstart demonstrates how to construct a basic Envoy HTTP Listener configuration using the Python dataclasses provided by the `envoy-data-plane` library. It defines an HTTP connection manager filter and wraps it in a network filter chain, then attaches it to a listener bound to port 8080. The resulting configuration is then serialized to JSON.
from envoy.config.listener.v3.listener import Listener
from envoy.config.listener.v3.listener_components import Filter, FilterChain
from envoy.extensions.filters.network.http_connection_manager.v3.http_connection_manager import HttpConnectionManager
# Define a simple HTTP connection manager filter
http_filter = HttpConnectionManager(
stat_prefix="ingress_http",
route_specifier=HttpConnectionManager.RouteSpecifier(route_config_name="local_route")
)
# Define a network filter chain with the HTTP connection manager
filter_chain = FilterChain(
filters=[
Filter(
name="envoy.filters.network.http_connection_manager",
typed_config=http_filter.to_json_string()
)
]
)
# Define an HTTP listener
listener = Listener(
name="listener_0",
address=Listener.Address(
socket_address=Listener.Address.SocketAddress(
address="0.0.0.0",
port_value=8080
)
),
filter_chains=[filter_chain]
)
# Print the generated Envoy Listener configuration (usually serialized to YAML or JSON for Envoy)
import json
print(json.dumps(listener.to_dict(), indent=2))
Debug
Known issues
breakingEnvoy's xDS API v2 was deprecated in Envoy 1.17 and removed in Q1 2021. This library exclusively uses the v3 API definitions. Attempting to use v2 API concepts or older import paths will result in errors.fixEnsure all imports and configuration strictly adhere to the `v3` package structure (e.g., `envoy.config.listener.v3.listener`).
affects: <= 1.x (of Envoy data plane API)
gotchaThis library provides Python *dataclass representations* of the Envoy Data Plane API. It is not a control plane implementation itself. Users are responsible for building their own control plane logic to generate, manage, and deliver this configuration to Envoy proxies.fixUnderstand that the library facilitates configuration generation; it does not handle gRPC xDS server implementation, state management, or pushing configuration to Envoy instances.
affects: All versions
gotchaThe `envoyproxy/data-plane-api` GitHub repository, from which this library is derived, is a read-only mirror of the API definitions within the main `envoyproxy/envoy` repository. Updates to the Python library are dependent on its maintainers tracking and converting upstream changes.fixMonitor the `envoy-data-plane` PyPI and GitHub project for updates. If a specific API version is needed that isn't yet available, consider raising an issue with the maintainers.
affects: All versions
gotchaThe library typically uses `betterproto` for dataclass generation, meaning the objects often include methods like `to_dict()` and `to_json_string()` for serialization. Be aware of these methods for converting dataclass objects into a format suitable for Envoy, rather than expecting direct `protobuf` message handling.fixUtilize the provided serialization methods (e.g., `to_dict()`, `to_json_string()`) on the dataclass instances to obtain the desired JSON or dictionary representation for Envoy configuration.
affects: All versions
Upgrade
Version history
2.2.0latest on PyPI · released Jul 21, 2026
Audit
Dependencies
No dependency data recorded yet.