Install & Compatibility
Where this runs
tested against v1.81.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 40.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.0s · import 0.000s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
channelz
✓ import grpc.experimental.channelz
Imports the module that registers the Channelz service on the server-side. Simply importing it is often enough to enable the service.
ChannelzStub
✓ from grpcio_channelz.proto.channelz_pb2_grpc import ChannelzStub
✗ from grpc.channelz_pb2_grpc import ChannelzStub
Client-side stub for interacting with the Channelz service, located within the grpcio-channelz package.
GetTopChannelsRequest
✓ from grpcio_channelz.proto.channelz_pb2 import GetTopChannelsRequest
✗ from grpc.channelz_pb2 import GetTopChannelsRequest
Client-side message definitions for Channelz requests/responses, located within the grpcio-channelz package.
This quickstart demonstrates how to enable the Channelz service on a gRPC server and then query it from a client. On the server-side, simply importing `grpc.experimental.channelz` is usually sufficient to register the service. The client then uses generated stubs and message definitions from `grpcio-channelz` to make RPC calls to the Channelz service.
import grpc
import grpc.experimental.channelz
from concurrent import futures
# For client-side querying
from grpcio_channelz.proto.channelz_pb2 import GetTopChannelsRequest
from grpcio_channelz.proto.channelz_pb2_grpc import ChannelzStub
# --- Server-side: Enable Channelz (simple import is often enough) ---
def serve():
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
# Simply importing grpc.experimental.channelz registers the service.
# You could explicitly add it if needed, but for basic setup, import is enough.
# grpc.experimental.channelz.add_server_channelz_stub(server) # Not strictly necessary if imported
server.add_insecure_port('[::]:50051')
server.start()
print("Server started on port 50051. Channelz enabled.")
return server
# --- Client-side: Query Channelz ---
def query_channelz(server_address='localhost:50051'):
with grpc.insecure_channel(server_address) as channel:
stub = ChannelzStub(channel)
try:
# Query for top channels
response = stub.GetTopChannels(GetTopChannelsRequest(started_channel_id=0, max_results=10))
print("\n--- Channelz Top Channels ---")
for channel_info in response.channel: # Use .channel, not .top_channel
print(f"ID: {channel_info.ref.channel_id}, State: {channel_info.data.state.state}, Target: {channel_info.data.target}")
except grpc.RpcError as e:
print(f"Error querying Channelz: {e.code().name} - {e.details()}")
if __name__ == '__main__':
server = serve()
# Allow some time for server to start and channels to register
import time
time.sleep(2)
# Make a dummy call to ensure a channel is created and visible to channelz
with grpc.insecure_channel('localhost:50051') as client_channel:
try:
# Just connect, no actual rpc needed to create a channel
grpc.channel_ready_future(client_channel).wait(timeout=1)
print("Dummy client connection made to register a channel.")
except grpc.FutureTimeoutError:
print("Dummy client connection timed out, but channel might still be visible.")
query_channelz()
server.stop(0) # Stop server gracefully
Debug
Known issues
gotchaThe `grpcio-channelz` package itself primarily provides the Protobuf definitions and service implementation, but you interact with Channelz on the server-side through `grpc.experimental.channelz` from the main `grpcio` library. It's a common confusion point that installing `grpcio-channelz` doesn't expose its own direct Python API for server enablement.fixEnsure both `grpcio` and `grpcio-channelz` are installed. For server-side enablement, use `import grpc.experimental.channelz`. For client-side querying, import stubs/messages from `grpcio_channelz.proto.channelz_pb2_grpc` and `grpcio_channelz.proto.channelz_pb2`.
affects: All versions
gotchaEnabling Channelz introduces a slight performance overhead due to the collection of runtime metrics and state. Additionally, Channelz exposes internal system details that should be secured and not exposed to untrusted parties in production environments without proper authentication and authorization.fixOnly enable Channelz when necessary for debugging or monitoring. In production, ensure Channelz endpoints are protected by gRPC authentication/authorization mechanisms or network firewalls to restrict access to authorized personnel only.
affects: All versions
deprecatedThe `channelz` module was long considered `experimental` within gRPC. While the import path `grpc.experimental.channelz` remains, its stability has improved significantly. However, users should still be aware that APIs marked 'experimental' might evolve faster than stable APIs.fixAlways refer to the latest gRPC documentation for the most current best practices. While the API has stabilized, continue to monitor gRPC release notes for any breaking changes related to `experimental` modules.
affects: <= 1.48.x (prior to general stability improvements)
Upgrade
Version history
1.81.1latest on PyPI · released Jun 11, 2026
Audit
Dependencies
grpciorequiredProvides the core gRPC framework and the experimental.channelz module for activation.