Fast Healthchecks

Framework-agnostic health checks with integrations for the most popular ASGI frameworks: FastAPI / FastStream / Litestar to help you implement the Health Check API pattern

Installation

pip install fast-healthchecks (or poetry add / uv add). Backends and framework integrations are optional extras. See documentation → Installation for all options and extra names.

Quick Start

from fastapi import FastAPI
from fast_healthchecks import Probe
from fast_healthchecks.integrations.fastapi import HealthcheckRouter

app = FastAPI()
app.include_router(HealthcheckRouter(Probe(checks=[...])))

from fast_healthchecks import Probe
from fast_healthchecks.integrations.faststream import health

# or: from fast_healthchecks.integrations.litestar import health
routes = health(Probe(checks=[...]))

Usage depends on the framework (FastAPI: HealthcheckRouter; FastStream / Litestar: health() from the corresponding integration). Full examples, configuration, lifecycle and shutdown, URL/SSRF, and DSN formats are in the documentation. Example projects: FastAPI, FastStream, Litestar.

• Configuration, shutdown, probe options: documentation.
• Public API and to_dict(): API Reference.
• PostgreSQL TLS and certificate rotation: DSN formats.

Probe Runner (Advanced)

For fine-grained control over probe execution, use ProbeRunner as an async context manager:

from fast_healthchecks import Probe
from fast_healthchecks.execution import ProbeRunner, RunPolicy

probe = Probe(name="my-probe", checks=[...])

# Use context manager for automatic resource cleanup
async with ProbeRunner(
    policy=RunPolicy(
        mode="reporting",
        execution="sequential",
        probe_timeout_ms=5000,  # 5 second timeout per probe
    )
) as runner:
    report = await runner.run(probe)
    # Runner automatically closes probes on exit

Key features:

• RunPolicy: Customize execution mode (strict/reporting), timeout, and health evaluation
• Automatic cleanup: Probes are closed when exiting the async with block
• Reusable runner: Run multiple probes with the same policy

See documentation for details.

Development

For the full list of recipes and their descriptions, run just or just --list (source of truth: justfile).

• Changelog: CHANGELOG.md in the repo; Changelog in the online docs.
• Architecture decisions: Decisions (ADR) in the online docs.
• Security: See SECURITY.md for how to report vulnerabilities.

Setup environment

git clone https://github.com/ZYLVEXT/fast-healthchecks.git
cd fast-healthchecks
uv sync --group=dev --group=docs --all-extras

Run linters

just lint

Running tests

• Import tests: just tests-imports — verifies ImportError messages when optional deps are missing; runs with minimal install (uv sync --group=dev only, no extras).
• Unit tests: just tests-unit — runs pytest with -m unit. Expects dev deps and optional extras already installed (e.g. after uv sync --group=dev --all-extras or after just tests-integration). FastStream unit tests use TestKafkaBroker(connect_only=True) and TestApp so no real Kafka is required.
• Integration tests: just tests-integration — requires Docker and docker compose; brings services up, runs integration tests, then brings them down. Copy .env.example to .env and override the service ports and matching DSNs there when the defaults are already in use. Set DOCKER_SERVICES_UP=1 to skip compose up/down when services are already running.
• Full suite: just tests-all — runs import tests, then integration (compose up, pytest integration, compose down), then unit tests. Requires Docker.

Certificates in tests/certs/ are for tests only; see CONTRIBUTING § Test certificates.

CI runs prek and the complete import, integration, and unit test suite on pushes to main, pull requests, version tags, and manual workflow dispatches.

Serve documentation

just serve-docs

Release and CI (maintainers)

Bump, rollback, workflows, secrets, prek, and dependency updates: see CONTRIBUTING § CI and release and the workflows table there. Quick links: Bump version, Rollback release.

Known alternatives

• FastAPI Health
• FastAPI Health Monitor
• fastapi_healthz
• fastapi_healthcheck

License

This project is licensed under the terms of the MIT license.