19.2.3.5 Stop Kill Contrast

docker stop and docker kill both terminate a running container, but they differ fundamentally in how that termination is achieved. docker stop attempts graceful shutdown by giving the process an opportunity to clean up before forcing it to exit. docker kill bypasses that opportunity entirely and terminates the process immediately or with a specific signal. Choosing between them depends on whether preserving application state and data integrity is worth the time it takes for a clean shutdown.

Core Behavioral Difference

docker stop sends SIGTERM, waits for the process to exit, and only sends SIGKILL if the timeout expires:

docker stop my-container

docker kill sends SIGKILL by default (or any signal you specify) without waiting:

docker kill my-container

Signal Comparison

When to Use docker stop

Use docker stop for all normal shutdown scenarios — deployments, restarts, maintenance, and scaling operations. Applications should be designed to handle SIGTERM and complete their shutdown within the configured timeout.

docker stop --time 30 my-database

Appropriate when:

• The container runs a database, queue, or other stateful service that must flush pending writes.
• HTTP servers need to drain in-flight requests before shutting down.
• Workers need to acknowledge message processing before disconnecting.

When to Use docker kill

Use docker kill when:

• The container's process is completely unresponsive (stuck in an infinite loop, deadlocked, blocking on a syscall that never returns).
• docker stop has already been attempted and is not making progress.
• The container must be terminated immediately and data consistency is not a concern (test cleanup, ephemeral containers).
• You need to send a non-terminating signal (e.g., SIGHUP to reload configuration) — docker kill is the only way to send arbitrary signals.

# Force kill an unresponsive container
docker kill stuck-container

# Reload nginx configuration without restarting the container
docker kill --signal SIGHUP nginx-container

Sending Custom Signals with docker kill

docker kill --signal can send any signal by name or number:

docker kill --signal SIGUSR1 my-container
docker kill --signal SIGHUP my-container
docker kill --signal 10 my-container   # SIGUSR1 by number

This allows triggering application-defined behaviors without stopping the container. A container receiving SIGUSR1 might dump its internal state for debugging. A container receiving SIGHUP might reload its configuration file without restarting.

Comparing Exit Codes

An exit code of 137 tells you the process was killed by SIGKILL — either because docker kill was used, or because docker stop's timeout expired.

The Speed Tradeoff

docker stop introduces latency equal to however long the process takes to shut down (up to the timeout). In a deployment that replaces 20 containers, each taking 5 seconds to shut down gracefully, the total shutdown phase takes 100 seconds (sequential by default).

docker kill terminates each container almost instantly but potentially leaves data in an inconsistent state — partial writes, open transactions, un-flushed caches, lost in-flight requests.

docker rm -f Combines Both

docker rm -f is a shorthand that sends SIGKILL (like docker kill) and then removes the container:

docker rm -f my-container

It does not use SIGTERM at all. It is the fastest way to stop and remove a container, suitable when the container's state does not matter.

Summary

docker stop → SIGTERM → wait → (SIGKILL if timeout) → container exits gracefully
docker kill → SIGKILL → container exits immediately
docker kill --signal X → custom signal → container may exit or act on signal
docker rm -f → SIGKILL + remove → container exits immediately and is deleted

Always prefer docker stop for production workloads. Reserve docker kill for unresponsive containers, signal-based application control, and ephemeral test environments.