6.1.3.2 Stop Timeout Behavior

Stop timeout behavior governs how long Docker waits, after sending SIGTERM, before forcibly terminating a container's main process with SIGKILL if it has not yet exited on its own — a grace period that gives an application time to shut down cleanly but that cannot wait indefinitely.

The Default Timeout

By default, docker stop waits ten seconds after sending SIGTERM before resorting to SIGKILL.

docker stop myapp

If the application running inside myapp hasn't exited within ten seconds of receiving SIGTERM, Docker forcibly kills it at that point.

Adjusting the Timeout

An application that legitimately needs more time to shut down gracefully — finishing a longer-running operation, draining a larger number of in-flight connections — can be given a longer grace period explicitly.

docker stop --time=30 myapp

Why a Forceful Kill Is Sometimes Unavoidable

Without an eventual forceful termination, a container whose main process never responds to SIGTERM (due to a bug, a hang, or simply not handling the signal at all) would remain stuck indefinitely, unable to actually stop — the timeout ensures docker stop always eventually succeeds in stopping the container, even if not gracefully.

docker stop --time=5 myapp

A shorter timeout might be appropriate for an application known to shut down quickly, reducing how long an operator has to wait if it does turn out to be unresponsive.

Observing Whether a Graceful or Forceful Stop Occurred

Reviewing what actually happened during a stop can reveal whether the application shut down gracefully within the timeout or had to be forcefully killed.

docker logs myapp
docker inspect myapp --format '{{.State.ExitCode}}'

Why Stop Timeout Behavior Matters

Understanding and appropriately configuring the stop timeout balances giving an application genuinely sufficient time to shut down cleanly against not waiting excessively long for a container that, for whatever reason, never responds to the graceful signal at all.