How to Check Container Health in Docker: Commands & Examples

To check container health in Docker, use the docker ps command to see the health status column if a healthcheck is defined. You can also inspect detailed health info with docker inspect --format='{{json .State.Health}}' <container>.

Syntax

The main commands to check container health are:

• docker ps: Lists running containers and shows health status if healthcheck is set.
• docker inspect --format='{{json .State.Health}}' <container>: Shows detailed healthcheck results for a specific container.

Here, <container> is the container ID or name.

bash

docker ps

docker inspect --format='{{json .State.Health}}' <container>

Example

This example shows how to run a container with a healthcheck and then check its health status.

bash

docker run -d --name mynginx \
  --health-cmd='curl -f http://localhost/ || exit 1' \
  --health-interval=10s \
  --health-retries=3 \
  nginx:1.23

docker ps

docker inspect --format='{{json .State.Health}}' mynginx

Output

CONTAINER ID   IMAGE        COMMAND                  CREATED          STATUS                    PORTS     NAMES
abcd1234efgh   nginx:1.23   "/docker-entrypoint.…"   10 seconds ago   Up 8 seconds (healthy)              mynginx

{"Status":"healthy","FailingStreak":0,"Log":[{"Start":"2024-06-01T12:00:10.000000000Z","End":"2024-06-01T12:00:10.500000000Z","ExitCode":0,"Output":""}]}

Common Pitfalls

Common mistakes when checking container health include:

• Not defining a HEALTHCHECK in the Dockerfile or run command, so no health status appears.
• Using a health command that always succeeds or fails, giving misleading results.
• Expecting health status on stopped containers; health is only shown for running containers.

bash

docker run -d --name badhealth nginx:1.23

docker ps

# No health status shown because no healthcheck defined

# Correct way: add a healthcheck

docker run -d --name goodhealth \
  --health-cmd='curl -f http://localhost/ || exit 1' \
  nginx:1.23

Quick Reference

Summary tips for checking Docker container health:

• Use docker ps to quickly see health status if healthcheck is set.
• Use docker inspect for detailed health info.
• Always define a meaningful HEALTHCHECK in your Dockerfile or run command.
• Health status updates only for running containers.

Key Takeaways

Use docker ps to see container health status if a healthcheck is defined.

Use docker inspect with .State.Health for detailed health information.

Define a proper HEALTHCHECK in your Dockerfile or run command for accurate health monitoring.

Health status is only available for running containers.

Avoid health commands that always succeed or fail to get meaningful health results.