19.2.3 Stop CLI Command

docker stop gracefully stops one or more running containers by sending a SIGTERM signal to the container's primary process (PID 1), waiting for it to exit cleanly, and then sending SIGKILL if the process does not exit within the timeout period. This two-phase approach gives well-behaved applications an opportunity to finish in-progress operations, flush buffers, close connections, and release resources before being forcefully terminated.

Basic Syntax

docker stop [OPTIONS] CONTAINER [CONTAINER...]

The container can be identified by its name or ID (full or short).

Stopping a Single Container

docker stop web-server

Docker sends SIGTERM to the container's main process. If the process does not exit within 10 seconds (the default timeout), Docker sends SIGKILL to force termination. After the container stops, it transitions to the exited state.

Stopping Multiple Containers

docker stop web-server database cache

Containers are stopped sequentially, each receiving SIGTERM followed by the timeout before SIGKILL if necessary.

Custom Timeout

The default grace period is 10 seconds. The -t (or --time) flag changes this:

docker stop --time 30 web-server

A longer timeout is appropriate for:

• Database containers that need to flush WAL (write-ahead log) to disk.
• Application servers that wait for in-flight requests to complete.
• Containers performing batch jobs that should not be interrupted mid-operation.

A shorter timeout is appropriate for:

• Fast-fail situations where immediate shutdown is acceptable.
• Containers whose main process ignores SIGTERM (they will wait the full timeout before being killed anyway).

Setting timeout to 0 is equivalent to docker kill — SIGKILL is sent immediately:

docker stop --time 0 web-server

Stopping All Running Containers

docker stop $(docker ps -q)

docker ps -q returns the IDs of all running containers, which are passed as arguments to docker stop.

On Windows PowerShell:

docker ps -q | ForEach-Object { docker stop $_ }

Signal Sequence

Exit Codes After Stop

After a graceful stop, the exit code is typically:

• 143 — The process received and handled SIGTERM (143 = 128 + 15, where 15 is SIGTERM's signal number).
• 0 — The process caught SIGTERM and exited cleanly with code 0.
• 137 — The process did not exit within the timeout and was killed by SIGKILL (137 = 128 + 9).

Any other non-zero code is the application's own exit code set before termination.

Verifying a Container Has Stopped

docker ps -a --filter "name=web-server"

CONTAINER ID   IMAGE          COMMAND    CREATED        STATUS                      NAMES
a1b2c3d4e5f6   nginx:latest   "nginx…"   3 hours ago    Exited (143) 2 seconds ago  web-server

The container is now in the exited state. It can be restarted or removed.

Stop vs. Kill

docker stop and docker kill both stop a container, but they differ in approach:

Use docker stop as the default for shutting down containers. Use docker kill only when the process is unresponsive and must be forcibly terminated.

Containers That Ignore SIGTERM

Some processes, particularly those running as PID 1 in a container without a proper init system, ignore SIGTERM by default (e.g., shell scripts that do not set up trap handlers). For these containers, the full timeout elapses before SIGKILL is sent, making docker stop slow.

Solutions:

• Use a minimal init process (such as tini or Docker's built-in --init flag) to properly handle signal propagation.
• Override the container's stop signal in the Dockerfile:

  STOPSIGNAL SIGINT
  

• Specify the signal at run time via docker stop with --signal (note: docker stop does not have this flag — use docker kill --signal for custom signals, then follow with docker stop if needed).

Restart Policies and Stop

If a container was started with --restart always or --restart unless-stopped, stopping it with docker stop sets an internal "intentionally stopped" flag. The container does not restart automatically after a graceful docker stop, regardless of the restart policy. It will restart only when the Docker daemon itself restarts (for unless-stopped, it will not restart even then).

Stopping and Immediately Removing

A common pattern stops and removes in sequence:

docker stop web-server && docker rm web-server

Or combine stop and remove with force:

docker rm -f web-server

docker rm -f sends SIGKILL (bypassing the grace period) and removes the container in one step. It should be used only when immediate cleanup is acceptable.