164

What's the difference between docker stop and docker kill?

Afaik, both will stop a running container. Is it that docker stop attempts to stop the process run inside the container in the correct way, while docker kill will send a kill signal? If so how would docker stop know how to correctly stop the running process. (Since this differs from process to process)

Improve this question

4 Answers 4

Reset to default
151

Is it that docker stop attempts to stop the process run inside the container in the correct way, while docker kill will send a kill signal?

Basically yes, the difference is subtle, but outlined in the Command Line reference:

  • docker stop: Stop a running container (send SIGTERM, and then SIGKILL after grace period) [...] The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL. [emphasis mine]
  • docker kill: Kill a running container (send SIGKILL, or specified signal) [...] The main process inside the container will be sent SIGKILL, or any signal specified with option --signal. [emphasis mine]

So stop attempts to trigger a graceful shutdown by sending the standard POSIX signal SIGTERM, whereas killjust kills the process by default (but also allows to send any other signal):

The SIGTERM signal is sent to a process to request its termination. Unlike the SIGKILL signal, it can be caught and interpreted or ignored by the process. This allows the process to perform nice termination releasing resources and saving state if appropriate. It should be noted that SIGINT is nearly identical to SIGTERM.

While not enforced in anyway, processes are generally expected to handle SIGTERM gracefully and do the right thing depending on their responsibilities - this can easily fail due to the graceful shutdown attempt taking longer than the grace period though, which is something to consider if data integrity is paramount (e.g. for databases); see e.g. Major Hayden's SIGTERM vs. SIGKILL for a more detailed explanation:

The application can determine what it wants to do once a SIGTERM is received. While most applications will clean up their resources and stop, some may not. An application may be configured to do something completely different when a SIGTERM is received. Also, if the application is in a bad state, such as waiting for disk I/O, it may not be able to act on the signal that was sent.

Improve this answer
3
  • 2
    So if I wanted to have a generic shutdown procedure for containers, I would have to catch the SIGTERM in the supervisor/runit process?
    – CMCDragonkai
    Aug 15, 2014 at 9:01
  • What's the best practice here? I understand why we would use docker kill by hand to save some time during shutdown, but in a script, wouldn't it always better to attempt a graceful shutdown via docker stop? I'm still seeing lots of docker kills in scripts though.
    – Dennis
    Jun 26, 2018 at 16:52
  • Worth mentioning that PID 1 of a container will by default ignore SIGTERM, defeating the point of stop. Using an entrypoint script with explicit trap might help; a simpler option is using a dedicated "container init system" as the entrypoint, docker run --init arranges that transparently without changing the image.
    – Beni Cherniavsky-Paskin
    May 19, 2020 at 18:07
19

docker kill will stop the main entrypoint process/program abruptly

docker stop will try to stop it gracefully (will ask politely :P)

in both cases the filesystem changes will be persisted (at the time of stop or kill) so if you docker start <container> then it will continue from there.

Improve this answer
3
  • 1
    ...but in case of docker kill any pending file system changes that the main process still had in memory will be lost, so the file system might end up damaged?
    – Arjan
    Apr 29, 2017 at 14:35
  • obviously , since is an abrupt stop, only changes at the time of kill will be persisted. Anything pending will be lost. My point was that docker kill is not really... killing the container, its stopping the process. like when you power off your computer instead of shutting down
    – awkwardarts
    Apr 30, 2017 at 8:11
  • 3
    Docker containers are not VMs and the kernel stays alive through a kill. Therefore, any filesystem changes that have reached the kernel will be committed intact. It shouldn't be possible to damage the filesystem (in the fsck sense; the application might not like losing some of its writes). docker kill is analogous to killing a process, not powering off the computer.
    – Ian Howson
    Dec 31, 2018 at 16:40
6

And addition to the answers added earlier

running docker events after docker stop shows events

  • kill (signal 15): where signal 15 = SIGTERM
  • die
  • stop

running docker events after docker kill shows events

  • kill (signal 9): where signal 9 = SIGKILL
  • Die (exit Code 137)

docker stop has a timeout before killing the process. The default is 10 seconds.

This table has even more details.

Improve this answer
2

It is analogous to Pulling the Plug off Desktop and Shutting down the computer

Like pulling the Plug Off means hard power off, docker kill means s direct way to kill my_container, which does not attempt to shut down the process gracefully first.

Shutting down the computer means sending a signal to OS for shutting down all the processes where docker stop means sending SIGTERM signal to the running container to stop the processes gracefully.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .