Log in

Video Lesson: Stop a container with a signal in Docker

Stop a container with a signal in Docker

Learn how to use Docker stop signals like SIGTERM, SIGKILL, and customize container shutdowns with specific exit codes.

Lesson Content

By default when you run docker stop (or docker restart), Docker sends a SIGTERM signal to your container.

These two commands do exactly the same thing:

docker stop myapp
docker stop -s SIGTERM

The -s (or --signal) flag lets you send a different signal instead of the default SIGTERM. This gives you more control over how your containers shut down.

Available Docker stop signals

Here are the signals you'll use most often:

  • 1 = HUP ("Hang up") - Originally meant the terminal disconnected. Now it's commonly used to reload configuration files without restarting
  • 2 = INT ("Interrupt") - Same as hitting Ctrl+C. Asks the process to shut down gracefully
  • 3 = QUIT ("Quit") - Terminates and creates a core dump for debugging
  • 9 = KILL ("Kill") - The nuclear option. Immediately terminates the process — it can't be caught or ignored
  • 15 = TERM ("Terminate") - Politely asks the process to shut down (Docker's default)

Exit codes and what they mean

When a process gets stopped by a signal, it leaves behind an exit code. This can be calculated with a simple formula:

Exit code = 128 + signal number

So if you stop a container with SIGQUIT (signal 3), you'll see exit code 131 (128 + 3).

Here's a quick reference:

Signal Number Exit Code Calculation
SIGHUP 1 129 128 + 1
SIGINT 2 130 128 + 2
SIGQUIT 3 131 128 + 3
SIGKILL 9 137 128 + 9
SIGTERM 15 143 128 + 15

Quick tip: You can drop the SIG prefix when using these. For example, just write KILL instead of SIGKILL.

Now these exit numbers are synonymous with how UNIX works with processes, however they don’t exactly apply to Docker containers. If you stop a container with HUP, INT, QUIT or TERM, it will eventually shutdown gracefully and with an exit code of 0, meaning everything shutdown properly.

However, if we do send in a KILL signal, it will have a different exit code.

Identify which signal stopped your container

Let's forcefully kill a container and see what Docker tells us:

$ docker start myapp

$ docker stop -s KILL myapp

myapp

$ docker ps -af name=myapp

CONTAINER ID   IMAGE     COMMAND                  CREATED       STATUS                        PORTS     NAMES
e1aa3fad4536   nginx     "/docker-entrypoint.…"   11 days ago   Exited (137) 16 minutes ago             myapp

If you check out the Status column, you’ll see that it shows Exited (137).

That 137 tells us exactly what happened: the container was forcefully killed (signal 9 + 128 = 137). If it had stopped gracefully with the default SIGTERM, we'd see exit code 0 instead.

So these containers provide you with a bit more information about how the container shut down.