{"id":508,"library":"grpcio-health-checking","title":"gRPC Health Checking","description":"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.","status":"active","version":"1.78.0","language":"python","source_language":"en","source_url":"https://github.com/grpc/grpc/tree/master/src/python/grpcio_health_checking","tags":["grpc","health check","microservices","monitoring"],"install":[{"cmd":"pip install grpcio-health-checking grpcio","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core gRPC library required for server and client functionalities.","package":"grpcio"}],"imports":[{"symbol":"health","correct":"from grpc_health.v1 import health"},{"symbol":"health_pb2","correct":"from grpc_health.v1 import health_pb2"},{"symbol":"health_pb2_grpc","correct":"from grpc_health.v1 import health_pb2_grpc"},{"symbol":"HealthServicer","correct":"from grpc_health.v1.health import HealthServicer"}],"quickstart":{"code":"import grpc\nimport time\nfrom concurrent import futures\nfrom grpc_health.v1 import health_pb2, health_pb2_grpc\nfrom grpc_health.v1.health import HealthServicer\n\n# --- Server Side ---\nclass MyServiceServicer(object):\n    def SayHello(self, request, context):\n        return health_pb2.HealthCheckResponse()\n\ndef serve():\n    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))\n\n    # Add your own gRPC service here if you have one\n    # my_service_pb2_grpc.add_MyServiceServicer_to_server(MyServiceServicer(), server)\n\n    health_servicer = HealthServicer()\n    health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)\n\n    # Set initial status for the overall server (empty string) and a specific service\n    health_servicer.set('', health_pb2.HealthCheckResponse.ServingStatus.SERVING)\n    health_servicer.set('MyService', health_pb2.HealthCheckResponse.ServingStatus.SERVING)\n\n    server.add_insecure_port('[::]:50051')\n    server.start()\n    print('Server started on port 50051...')\n    \n    try:\n        while True:\n            time.sleep(86400) # One day in seconds\n    except KeyboardInterrupt:\n        health_servicer.enter_graceful_shutdown() # Important for client notification\n        server.stop(0)\n\n# --- Client Side ---\ndef check_health():\n    with grpc.insecure_channel('localhost:50051') as channel:\n        stub = health_pb2_grpc.HealthStub(channel)\n        try:\n            # Check overall server health\n            response_overall = stub.Check(health_pb2.HealthCheckRequest(service=''))\n            print(f\"Overall Server Health: {health_pb2.HealthCheckResponse.ServingStatus.Name(response_overall.status)}\")\n\n            # Check specific service health\n            response_my_service = stub.Check(health_pb2.HealthCheckRequest(service='MyService'))\n            print(f\"'MyService' Health: {health_pb2.HealthCheckResponse.ServingStatus.Name(response_my_service.status)}\")\n\n        except grpc.RpcError as e:\n            if e.code() == grpc.StatusCode.UNIMPLEMENTED:\n                print(\"Health checking is not implemented by the server.\")\n            else:\n                print(f\"Error checking health: {e.details}\")\n\nif __name__ == '__main__':\n    import threading\n\n    server_thread = threading.Thread(target=serve)\n    server_thread.daemon = True # Allow main program to exit even if thread is running\n    server_thread.start()\n\n    time.sleep(1) # Give server time to start\n    check_health()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, particularly noted with `grpcio==1.72.0` and `protobuf==6.31.0-rc1`."},{"fix":"Implement a shutdown hook (e.g., a `KeyboardInterrupt` handler) to call `health_servicer.enter_graceful_shutdown()` before stopping your gRPC server.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"search_vec":"'-3':54 '1.78.0':46 '2':53 'allow':24 'api':22 'avail':35 'balanc':28 'check':3,7,12,58 'client':26 'current':43 'everi':52 'grpc':1,15,25,40,56 'grpc.health':19 'grpcio':5 'grpcio-health-check':4 'health':2,6,11,37,57 'implement':17 'load':27 'microservic':59 'monitor':60 'month':55 'new':48 'occur':51 'orchestr':30 'provid':8 'releas':49 'server':16 'servic':13,21,41 'standard':10 'status':38 'system':31 'typic':50 'v1':20 'verifi':33 'version':44","created_at":"2026-03-28T15:16:37.984291+00:00","updated_at":"2026-04-16T15:29:42.291694+00:00","problems":{"verify_error":"error: Failed to parse: `grpcio-health-checking grpcio`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `g`\ngrpcio-health-checking grpcio\n                       ^"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.83.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://grpc.io","github":null,"docs":"https://grpc.github.io/grpc/python/grpc_health_checking.html","changelog":null,"pypi":"https://pypi.org/project/grpcio-health-checking/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"verified"}}