A Dockerfile HEALTHCHECK runs a command inside the container on a schedule and records whether the container is healthy or unhealthy. It tells the engine and tools that the process is still working, not that the software is secure or that the whole system is correct.
How it behaves
The Dockerfile reference describes three states. A container starts as starting. A passing check makes it healthy. After enough consecutive failures it becomes unhealthy. A check that runs longer than its timeout counts as failed.
| Option | Default |
|---|---|
| interval | 30 seconds |
| timeout | 30 seconds |
| start period | 0 seconds |
| start interval | 5 seconds, needs Docker Engine 25.0 or later |
| retries | 3 |
Exit codes matter. Zero means healthy. One means unhealthy. Two is reserved, so do not use it. A Dockerfile can have only one HEALTHCHECK, and if you write several, only the last takes effect. The instruction HEALTHCHECK NONE turns off a check inherited from the base image.
Write a check that tests something real
A good check exercises the thing users depend on. For a web service, call a local status endpoint that touches its main dependency. A check that only tests whether a port is open can pass while the app returns errors.
HEALTHCHECK CMD curl -f http://localhost:8080/healthz || exit 1
That example needs curl in the image. Minimal and distroless images often have no curl and no shell, so the check cannot run. Options are a tiny purpose built check binary copied from a build stage, or a health command built into your own application. Weigh that against the extra file in the image.
Use the start period
Slow starting apps fail early checks. Failures during the start period do not count toward retries, but once one check succeeds, later failures count. Set a start period that matches your real warm up time, or the engine will report a healthy app as unhealthy.
What a healthy flag does not prove
Healthy means the check command exited with zero. It does not mean the image has no known flaws, that the code is the version you meant to ship, or that an attacker is not inside. A compromised container can keep answering its health endpoint. So pair health checks with image scanning and runtime monitoring, and do not report healthy status as a security signal.
Also keep the check cheap and read only. A check that writes files or calls external services can cause its own outages, and a check that exposes detailed internal state on a public path leaks information.
Orchestrators
Some orchestrators use their own probes instead of the image setting. If you deploy to one that does, define the probes there and treat the Dockerfile instruction as a default for plain engine use. Check your platform docs for which one wins.
Quick check
Can I have two HEALTHCHECK lines?
You can write them, but only the last one takes effect.
Does an unhealthy container restart automatically?
Not by itself with the plain engine. The status is a signal. Restart behavior depends on your orchestrator or restart policy, so check how yours reacts.
Safeguard
Safeguard does SBOM and dependency scanning, and its policies and gates can run in CI so a bad image does not reach production. You can try a free scan before deciding anything.
Sources
Last reviewed: 19 October 2026.
