grpcio-reflection is the Python implementation of the standard Protobuf Reflection Service for gRPC. It enables gRPC clients to dynamically discover available services, their RPC methods, and associated message types at runtime, without needing pre-compiled .proto files. This is particularly useful for debugging tools like grpcurl and Postman. The library is currently at version 1.80.0 and follows the gRPC core's approximately six-week release cadence.
Install & Compatibility
Where this runs
tested against v1.81.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.930 runs
installs and imports cleanly · install 0.0s · import 0.568s · 40.1MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 2.9s · import 0.303s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
reflection
✓ from grpc_reflection.v1alpha import reflection
✗ import grpc_reflection.v1alpha.reflection
The common pattern is to import the 'reflection' module directly, not the parent package. The module provides functions like `enable_server_reflection` and the `SERVICE_NAME` constant.
This quickstart demonstrates how to enable server reflection for a gRPC Python server. It includes a mock gRPC service setup to illustrate the integration of `grpcio-reflection`. In a real application, you would replace the `MockService_pb2` and `MockService_pb2_grpc` with the actual modules generated from your `.proto` files using `grpcio-tools`. The `reflection.enable_server_reflection` function is called with a list of fully-qualified service names you wish to expose.
import grpc
from concurrent import futures
from grpc_reflection.v1alpha import reflection
# --- Simulate generated protobuf code ---
# In a real application, these would be generated by grpcio-tools
# from your .proto files (e.g., my_service.proto).
# For this example, we define minimal mock objects.
class MockService_pb2:
DESCRIPTOR = type('Descriptor', (object,), {'services_by_name': {'MyService': type('ServiceDescriptor', (object,), {'full_name': 'my.package.MyService'})}}})()
class MockService_pb2_grpc:
class MyServiceServicer:
def __init__(self):
pass
def add_MyServiceServicer_to_server(servicer, server):
print(f"Mock: Adding {servicer.__class__.__name__} to server")
# --- Real gRPC server with reflection ---
class MyServiceServicer(MockService_pb2_grpc.MyServiceServicer):
def MyMethod(self, request, context):
# In a real scenario, handle actual RPC logic
print(f"Received request for MyMethod: {request}")
return "Response from MyMethod"
def serve_with_reflection(port='[::]:50051'):
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
# Register your actual gRPC service implementation
MockService_pb2_grpc.add_MyServiceServicer_to_server(MyServiceServicer(), server)
# Enable server reflection
# List all service names you want to expose via reflection.
# This typically includes your custom services and the reflection service itself.
SERVICE_NAMES = (
MockService_pb2.DESCRIPTOR.services_by_name['MyService'].full_name,
reflection.SERVICE_NAME,
)
reflection.enable_server_reflection(SERVICE_NAMES, server)
server.add_insecure_port(port)
server.start()
print(f"Server with reflection enabled listening on {port}")
server.wait_for_termination()
if __name__ == '__main__':
# To run this, you'd typically have your actual .proto files compiled
# and replace MockService_pb2 and MockService_pb2_grpc with your generated ones.
# Example usage with grpcurl (after running this script):
# grpcurl -plaintext localhost:50051 list
# grpcurl -plaintext localhost:50051 list my.package.MyService
# grpcurl -plaintext -d '{"name": "World"}' localhost:50051 my.package.MyService/MyMethod
serve_with_reflection()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'grpc_reflection.v1alpha.reflection'
The 'grpcio-reflection' package, which provides the reflection service implementation, is either not installed or is not accessible in the current Python environment.
fixInstall the 'grpcio-reflection' package using pip: `pip install grpcio-reflection`
grpc.RpcError: StatusCode.UNIMPLEMENTED
This error, often accompanied by 'desc = unknown service', indicates that the gRPC server has not correctly enabled the reflection service or has not registered the target service (or the reflection service itself) with the reflection implementation.
fixEnsure `reflection.enable_server_reflection()` is called on your gRPC server, passing a list of all fully-qualified service names you wish to expose, including `reflection.SERVICE_NAME` for the reflection service itself. For example: `SERVICE_NAMES = (MyService_pb2.DESCRIPTOR.services_by_name['MyService'].full_name, reflection.SERVICE_NAME,) reflection.enable_server_reflection(SERVICE_NAMES, server)`
google.protobuf.runtime_version.VersionError: Detected incompatible Protobuf Gencode/Runtime versions
This error occurs when there is a version mismatch between the `protobuf` package used to compile the `.proto` files into Python code (gencode) and the `protobuf` runtime package installed in your environment.
fixEnsure that your `grpcio`, `grpcio-tools`, and `protobuf` packages are installed with compatible versions. It is often safest to install them together or ensure `protobuf` is at a version compatible with your `grpcio` installation. You might need to upgrade or downgrade `protobuf` (e.g., `pip install --upgrade protobuf==<compatible_version>`).
Audit
Dependencies
grpciorequiredCore gRPC library; grpcio-reflection depends on it for server and client functionalities.
protobufrequiredWhile grpcio itself decoupled from direct protobuf dependency in v1.12.0, grpcio-reflection directly uses protobuf for descriptor management. Ensure a compatible version is installed.