gRPC Health Checking

1.78.0 verified Tue May 12 auth: no python install: verified quickstart: verified

grpcio-health-checking provides a standard Health Checking Service for gRPC servers, implementing the `grpc.health.v1` service API. It allows gRPC clients, load balancers, and orchestration systems to verify the availability and health status of gRPC services. The current version is 1.78.0, with new releases typically occurring every 2-3 months.

pip install grpcio-health-checking grpcio

Common errors

error ModuleNotFoundError: No module named 'grpc-health-checking' ↓

cause The `grpcio-health-checking` package is not installed in your Python environment or there's a typo in the import statement (e.g., using a hyphen instead of an underscore in the package name during import, though the package itself is installed via `pip install grpcio-health-checking`).

fix

Install the package using pip: pip install grpcio-health-checking.

error google.protobuf.runtime_version.VersionError: Detected mismatched Protobuf Gencode/Runtime version suffixes when loading grpc_health/v1/health.proto: gencode X.Y.Z runtime A.B.C. ↓

cause This error occurs when the `grpcio-health-checking` package (or `grpcio` itself) is used with an incompatible version of the `protobuf` library, often due to `grpcio` installing a pre-release or slightly mismatched version of `protobuf`.

fix

Ensure compatible versions of grpcio and protobuf are installed. Explicitly install or downgrade protobuf to a stable version known to work with your grpcio version. For example, pip install grpcio==<version> protobuf==<compatible_version> or try pip install --upgrade grpcio protobuf to get the latest compatible stable versions. Often, reinstalling grpcio alone can resolve it by pulling the correct protobuf dependency: pip install --upgrade grpcio grpcio-health-checking.

error ImportError: cannot import name 'runtime_version' from 'google.protobuf' (.../google/protobuf/__init__.py) ↓

cause This `ImportError` typically indicates that `grpcio-health-checking` expects a `protobuf` version that includes the `runtime_version` module (introduced in protobuf 5.27.0 or later), but an older version of `protobuf` is installed.

fix

Upgrade your protobuf library to a version that includes the runtime_version module. A common fix is pip install --upgrade protobuf.

error UNIMPLEMENTED: Method not found: grpc.health.v1.Health/Check ↓

cause This gRPC status error means that a client is trying to call the `Check` method of the `grpc.health.v1.Health` service, but the gRPC server does not have the `HealthServicer` registered or correctly implemented.

fix

Ensure that you have correctly added the HealthServicer to your gRPC server. In Python, this involves creating a health.HealthServicer() instance and registering it with your server: health_pb2_grpc.add_HealthServicer_to_server(health.HealthServicer(), server).

Warnings

breaking Mismatched Protobuf Gencode/Runtime versions can lead to `google.protobuf.runtime_version.VersionError`. This occurs when `grpcio` and `grpcio-health-checking` are compiled or installed with incompatible versions of the `protobuf` package. ↓

fix Ensure that `grpcio` and `grpcio-health-checking` are installed in a clean environment and that their `protobuf` dependencies are compatible. Consider using a virtual environment and `pip install --upgrade grpcio grpcio-health-checking` to ensure consistent versions. Refer to Protobuf's cross-version runtime guarantee documentation.

gotcha It is crucial to notify the health check service when your gRPC server is shutting down gracefully. Failing to call `HealthServicer.enter_graceful_shutdown()` means connected clients will not be informed that the service is no longer serving, potentially leading to continued (and failed) health checks. ↓

fix Implement a shutdown hook (e.g., a `KeyboardInterrupt` handler) to call `health_servicer.enter_graceful_shutdown()` before stopping your gRPC server.

gotcha When a gRPC client performs a health check, if the `Check` or `Watch` RPC call fails with an `UNIMPLEMENTED` status, the client should assume that health checking is not supported by the server for that service and should disable further health checks for it. ↓

fix Clients should include logic to catch `grpc.StatusCode.UNIMPLEMENTED` errors and gracefully handle the absence of health checking functionality, typically by ceasing further health check attempts for that service.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.26s 40.0M

3.10 slim (glibc) - - 0.13s 38M

3.11 alpine (musl) - - 0.69s 42.6M

3.11 slim (glibc) - - 0.24s 40M

3.12 alpine (musl) - - 0.84s 34.3M

3.12 slim (glibc) - - 0.46s 32M

3.13 alpine (musl) - - 0.81s 34.0M

3.13 slim (glibc) - - 0.46s 32M

3.9 alpine (musl) - - 0.20s 39.5M

3.9 slim (glibc) - - 0.17s 37M

Imports

health
```
from grpc_health.v1 import health
```
health_pb2
```
from grpc_health.v1 import health_pb2
```

health_pb2_grpc

from grpc_health.v1 import health_pb2_grpc

HealthServicer

from grpc_health.v1.health import HealthServicer

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates both server-side implementation and client-side health checking. The server initializes a `HealthServicer`, adds it to the gRPC server, and sets the health status for the overall server (empty string) and a hypothetical 'MyService'. The client then uses a `HealthStub` to query these statuses. It includes handling for graceful shutdown notification and `UNIMPLEMENTED` status.

import grpc
import time
from concurrent import futures
from grpc_health.v1 import health_pb2, health_pb2_grpc
from grpc_health.v1.health import HealthServicer

# --- Server Side ---
class MyServiceServicer(object):
    def SayHello(self, request, context):
        return health_pb2.HealthCheckResponse()

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))

    # Add your own gRPC service here if you have one
    # my_service_pb2_grpc.add_MyServiceServicer_to_server(MyServiceServicer(), server)

    health_servicer = HealthServicer()
    health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)

    # Set initial status for the overall server (empty string) and a specific service
    health_servicer.set('', health_pb2.HealthCheckResponse.ServingStatus.SERVING)
    health_servicer.set('MyService', health_pb2.HealthCheckResponse.ServingStatus.SERVING)

    server.add_insecure_port('[::]:50051')
    server.start()
    print('Server started on port 50051...')
    
    try:
        while True:
            time.sleep(86400) # One day in seconds
    except KeyboardInterrupt:
        health_servicer.enter_graceful_shutdown() # Important for client notification
        server.stop(0)

# --- Client Side ---
def check_health():
    with grpc.insecure_channel('localhost:50051') as channel:
        stub = health_pb2_grpc.HealthStub(channel)
        try:
            # Check overall server health
            response_overall = stub.Check(health_pb2.HealthCheckRequest(service=''))
            print(f"Overall Server Health: {health_pb2.HealthCheckResponse.ServingStatus.Name(response_overall.status)}")

            # Check specific service health
            response_my_service = stub.Check(health_pb2.HealthCheckRequest(service='MyService'))
            print(f"'MyService' Health: {health_pb2.HealthCheckResponse.ServingStatus.Name(response_my_service.status)}")

        except grpc.RpcError as e:
            if e.code() == grpc.StatusCode.UNIMPLEMENTED:
                print("Health checking is not implemented by the server.")
            else:
                print(f"Error checking health: {e.details}")

if __name__ == '__main__':
    import threading

    server_thread = threading.Thread(target=serve)
    server_thread.daemon = True # Allow main program to exit even if thread is running
    server_thread.start()

    time.sleep(1) # Give server time to start
    check_health()