Killing and Waiting Containers

Containers don’t always stop exactly when you want them to. Sometimes a process is stuck and you need to terminate it immediately; other times, you want a script or another process to simply wait until a container finishes before continuing.

Docker provides two simple commands for these situations: docker kill and docker wait.

docker kill is about stopping a running container immediately, while docker wait is about waiting for a container to stop and retrieving its exit code.

Let’s understand what each command does and when they are useful.

Killing Containers

What Does It Mean?

Killing a container means sending a signal to the container’s main process so that it terminates.

The command is:

docker container kill <container-id>

By default, Docker sends the SIGKILL signal. Unlike docker stop, which normally gives the application some time to shut down gracefully, docker kill terminates the process immediately.

For example:

docker container kill mycontainer

You can also explicitly specify a signal:

docker container kill --signal SIGTERM mycontainer

This can be useful when you need more control over how the process is terminated.

Why Kill?

You typically use docker kill when a container needs to be terminated immediately.

Common situations include:

• A container is unresponsive or stuck.
• An application is not responding to normal shutdown signals.
• A process is consuming excessive resources.
• A container is stuck during shutdown.
• You need to quickly terminate a test or development container.
• An automated script needs an immediate termination mechanism.

For normal application shutdown, docker stop is usually preferred because it attempts a graceful shutdown first.

Common Patterns

Kill a container by name:

docker container kill mycontainer

Kill a container using its ID:

docker container kill 8f3c2a1b4d5e

Send a specific signal:

docker container kill --signal SIGTERM mycontainer

Kill multiple containers:

docker container kill container1 container2 container3

A useful pattern when troubleshooting is to first try a graceful stop:

docker container stop mycontainer

and use kill when the container does not respond as expected:

docker container kill mycontainer

Waiting for Containers

What Does It Mean?

docker wait waits until one or more containers stop running and then prints their exit code.

The command is:

docker container wait <container-id>

For example:

docker container wait mycontainer

The command doesn’t return immediately if the container is still running. Instead, it waits for the container to exit.

Once the container stops, Docker prints its exit code:

0

An exit code of 0 generally indicates successful completion, while a non-zero value usually indicates that the process ended with an error.

Why Wait?

docker wait is particularly useful when Docker is being used as part of a workflow or script.

For example, suppose you start a container to perform a task:

docker container run -d my-job

You may want your script to continue only after that job has finished.

Instead of repeatedly checking the container’s status, you can simply use:

docker container wait my-job

This makes docker wait useful for:

• Waiting for a batch job to finish.
• Running containers as one-off tasks.
• Coordinating multiple containers.
• Checking whether a container completed successfully.
• Writing shell scripts that depend on container completion.
• Using the container’s exit code to determine the next action.

Common Patterns

Wait for a container to finish:

docker container wait mycontainer

Capture the exit code in a shell variable:

exit_code=$(docker container wait mycontainer)
echo "Container exited with code: $exit_code"

Use the exit code in a script:

docker container wait mycontainer

if [ $? -eq 0 ]; then
    echo "Container completed successfully"
else
    echo "Container failed"
fi

You can also wait for multiple containers:

docker container wait container1 container2

Docker waits for the specified containers to stop and returns their exit statuses.

Kill vs Wait

Although both commands deal with container lifecycle, they solve completely different problems:

A simple way to remember them:

Kill = “Stop it now.”

Wait = “Tell me when it’s done.”