19.2.3.2 Stop Timeout Option

A focused guide to Stop Timeout Option, connecting core concepts with practical Docker and container operations.

The timeout option in docker stop controls how long Docker waits for a container's process to exit after receiving SIGTERM before escalating to SIGKILL. It is specified with the -t or --time flag and accepts an integer representing seconds. The default is 10 seconds.

Basic Usage

docker stop --time 30 my-container

docker stop -t 30 my-container

Both forms are equivalent. Docker sends SIGTERM to the container's PID 1, then waits up to 30 seconds. If the process exits before 30 seconds, the stop completes immediately. If it does not exit within 30 seconds, Docker sends SIGKILL.

The Default Timeout

When -t is not specified:

docker stop my-container

Docker uses a 10-second timeout. This is reasonable for most web applications and microservices that do not require extended cleanup periods. For processes that take longer to shut down, the default causes them to be forcefully killed.

Setting Timeout to Zero

A timeout of 0 is valid and means "do not wait at all — send SIGKILL immediately":

docker stop --time 0 my-container

This is functionally equivalent to docker kill my-container. The container is killed without any grace period. This is useful when you know the container's process does not implement signal handling and the wait would serve no purpose.

Container-Level Default Stop Timeout

The per-call -t flag overrides the timeout just for that invocation. A permanent default can also be set on the container when it is created or run, using --stop-timeout:

docker run -d --stop-timeout 60 --name my-database postgres:15

With this configuration, any subsequent docker stop my-database (without -t) will wait 60 seconds instead of the system default of 10.

Similarly, in a Dockerfile, a default stop timeout can be expressed using the STOPTIMEOUT instruction (not all Docker versions support this; --stop-timeout at run time is the more portable approach).

Choosing the Right Timeout

The appropriate timeout depends on how long the container's process needs to complete its shutdown:

Container Type	Recommended Timeout	Reason
Stateless HTTP servers	10–30 seconds	Wait for in-flight requests to complete
Database (PostgreSQL)	30–120 seconds	Flush WAL, complete checkpoint, close connections
Message queue consumer	30–60 seconds	Finish processing current message, commit offsets
Cache (Redis)	10–30 seconds	Persist RDB snapshot or AOF flush if persistence is enabled
Batch job container	120–300 seconds	Allow the current batch unit to complete
CI build container	5–10 seconds	No state to preserve; faster teardown is acceptable

A timeout that is too short causes the OOM killer or SIGKILL to interrupt partial operations, leading to corrupted data or incomplete transactions. A timeout that is too long delays deployments and rollouts unnecessarily.

Timeout in Docker Compose

Docker Compose respects per-service stop timeout settings:

services:
  database:
    image: postgres:15
    stop_grace_period: 60s
  web:
    image: myapp:1.0.0
    stop_grace_period: 15s

stop_grace_period in Compose corresponds directly to the -t flag in docker stop. When docker compose down or docker compose stop is run, each service gets its configured grace period.

Timeout and the Exit Code

The exit code of the stopped container reveals whether the process exited gracefully or was killed:

docker inspect --format '{{.State.ExitCode}}' my-container

0 or 143: The process responded to SIGTERM and exited on its own within the timeout.
137: The process was killed with SIGKILL — the timeout expired before the process exited.

An exit code of 137 after docker stop is a diagnostic indicator that the timeout was too short for the process's shutdown procedure.

Timeout in Deployment Pipelines

When rolling deployments replace containers one at a time, the timeout directly impacts deployment speed. If 10 containers are being replaced and each needs 30 seconds to shut down gracefully:

With default 10s timeout: each container is killed after 10 seconds, risking partial operations.
With 30s timeout: each container shuts down cleanly, but the deployment takes at least 30 seconds per batch.

Setting the timeout thoughtfully balances deployment speed against data safety.

Viewing the Current Stop Timeout of a Container

docker inspect --format '{{.HostConfig.StopTimeout}}' my-container

If the value is 0, the container uses the Docker daemon's default (10 seconds). If a non-zero value is shown, that is the timeout configured with --stop-timeout when the container was created.