Skip to main content

Opinionated healthcheck library

Project description

Python Healthcheck Lib

This is an opinionated library to help with structuring healthchecks in your python application.

It will not help you with the healthcheck logic itself, but it will help you build the response in a standard format.

We aim at supporting almost exactly the standard described in Although it's just a expired draft, it seems to be the better standard on healthchecks out there as of this writing.

This standard is not fully supported yet, see the roadmap for more information.


# With pip
pip install python-healthchecklib

# With poetry
poetry add python-healthchecklib


The main concepts to keep in mind when using this library are the service and components concepts.

We consider a service to be the application as a whole. It's the thing that is running and that you want to check the health of.

We consider components to be the different parts of the application that you want to check the health of, being them internal or external. For example, if you have a web application, you might want to check the health of the database, the cache, internal components, etc.

You'll be responsible for implementing the healthcheck logic for each component, but this library will help you build the response in a standard format and define the health of the service based on the health of its components.


The lib exposes asynchronous methods, which makes it easy to use with either sync or async codebases.

from healthcheck import Healthcheck, HealthcheckDatastoreComponent, HealthcheckCallbackResponse

# Create a healthcheck instance
healthcheck = Healthcheck(
    name="My Service"

# Create a component
db_component = HealthcheckDatastoreComponent(

# Define the healthcheck logic for the component.
# They should be async functions that return a HealthcheckCallbackResponse
async def db_healthcheck():
    # Implement some logic to check the health of the database
    return HealthcheckCallbackResponse(
        output="Database is healthy",

# Add the healthcheck logic to the component

# You can add more than one healthcheck to a component, which means that this is a component made of multiple instances.
async def db_healthcheck_2():
    # Implement some logic to check the health of the database
    return HealthcheckCallbackResponse(
        output="Responsive but high latency",


# Add the component to the healthcheck

# Get the health status of the service
status = await

# In case you're in a sync context, you can use `` to run the async code:
status =

# Print the status

# {
#   "status": "pass",
#   "description": "Health status of My Service",
#   "checks": {
#     "MySQL": [
#       {
#         "status": "pass",
#         "output": "Database is healthy",
#         "componentType": "datastore",
#         "componentName": "MySQL
#       },
#       {
#         "status": "warn",
#         "output": "Responsive but high latency",
#         "componentType": "datastore",
#         "componentName": "MySQL
#       }
#     ]
#   }
# }


We welcome contributions to help us achieve these goals. See below how to contribute.


See the contributing guide for more information.


By contributing to python-healthchecklib, you agree that your contributions will be licensed under the MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_healthchecklib-0.1.1.tar.gz (6.2 kB view hashes)

Uploaded Source

Built Distribution

python_healthchecklib-0.1.1-py3-none-any.whl (6.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page