Kill a Docker Container and Check What Happened

By the end, you will be able to stop a running Docker container immediately, send a specific Unix signal when that is what the application needs, and check that you targeted the intended container. The examples use Docker Engine and CLI 29.8.1, installed from docker-ce-cli.

Time: about five minutes for a known container, longer if you first need to identify its owner. You need a shell with access to the Docker daemon. That commonly means membership of the docker group or a rootless Docker setup. If the command reports a permission error, use sudo only when that is how this host is administered. Do not add your account to a privileged group just to get past one failed command.

Checkpoint: decide whether kill is appropriate

docker container kill sends a signal to the container's main process. With no signal selected, the default is SIGKILL. That is immediate and cannot be handled by the application, so buffered data may not be flushed and cleanup handlers will not run.

If the service can shut down cleanly, prefer docker container stop. It normally sends SIGTERM, waits for its grace period, and then uses SIGKILL if the process has not exited. Use kill for a wedged process, an emergency, or a deliberate non-default signal. Killing a container changes service state and can interrupt requests, writes and background jobs.

docker container stop CONTAINER_NAME
# Immediate termination instead:
docker container kill CONTAINER_NAME

There is no undo for a process that has been killed. You can usually start the stopped container again, but application recovery depends on its own persistence and transaction handling.

1. Identify the exact target

List running containers and copy the name or ID from the row you intend to affect. Names are easier to read, while an ID or unambiguous ID prefix is useful in scripts.

docker container ls --format 'table {{.ID}}	{{.Names}}	{{.Image}}	{{.Status}}'

Check the result before proceeding. A similar name, a Compose-generated suffix, or a container that has already restarted can turn a correct command into the wrong incident response. A stopped container is not a valid target for this command.

For a closer check, inspect one candidate without changing it:

docker container inspect CONTAINER_NAME +  --format 'name={{.Name}} status={{.State.Status}} pid={{.State.Pid}}'

Proceed only when the output shows the expected name and status=running. The command accepts a container name, full ID, or ID prefix, and accepts more than one container argument.

2. Send the default immediate signal

Replace CONTAINER_NAME with the value you just checked. The command prints the container reference after Docker accepts the request.

docker container kill CONTAINER_NAME

CONTAINER_NAME

Verify the state rather than treating that line as proof that the application has finished all its work:

docker container inspect CONTAINER_NAME +  --format 'status={{.State.Status}} finished={{.State.FinishedAt}} exit={{.State.ExitCode}}'

Normally the status becomes exited. The exit code is application and image dependent, so record it rather than assuming a particular number. If the container is managed by Compose, Swarm, Kubernetes or another supervisor, it may be started again immediately. That is a control-plane decision, not evidence that the signal was ignored.

3. Send a chosen signal when the process can handle it

Use --signal with a signal name or an unsigned number. The SIG prefix is accepted, and the numeric form follows the kernel signal numbering on the host.

docker container kill --signal=SIGINT CONTAINER_NAME
# Equivalent forms for signal 2:
docker container kill --signal=INT CONTAINER_NAME
docker container kill --signal=2 CONTAINER_NAME

A non-terminal signal does not necessarily stop the container. For example, SIGHUP often causes a service to reload configuration or simply continue running. Check immediately:

docker container inspect CONTAINER_NAME +  --format 'status={{.State.Status}}'

If the output is still running, that is a valid result. Do not repeat the command with SIGKILL until you have decided that an immediate termination is safe.

Signals can miss the application

Docker sends the signal to the container's main process. When an image uses shell-form ENTRYPOINT or CMD, the executable can instead be a child of /bin/sh -c. The shell may not pass the signal through, so the program you expected to handle it might not receive it. This is an image construction problem, not a reason to assume that every signal is equivalent.

Use the container's configured command and process list when diagnosing this:

docker container inspect CONTAINER_NAME +  --format 'path={{.Path}} args={{json .Args}}'
docker container top CONTAINER_NAME

If reliable signal handling matters, run the application as the container's intended main process or use an entrypoint that forwards signals. Test that behaviour with a disposable container before changing a production image.

Recovery after a mistaken kill

First check whether the container still exists. Killing it does not remove its writable container layer, named volumes or image.

docker container ps -a --filter name=CONTAINER_NAME
docker container start CONTAINER_NAME

The second command is safe only if restarting the service is safe. Confirm health, logs and dependent services afterwards:

docker container logs --tail=50 CONTAINER_NAME
docker container inspect CONTAINER_NAME +  --format 'status={{.State.Status}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}not-configured{{end}}'

If a supervisor owns the container, use that supervisor's restart or rollback procedure instead. Do not remove the container as a cleanup step unless you have separately confirmed that its data and replacement configuration are available.

Done means

• You checked the exact container name or ID and saw that it was running.
• You chose stop for graceful shutdown, or accepted the data-loss and interruption risk of kill.
• You verified the resulting state and exit information with docker container inspect.
• You know whether a supervisor may restart the container and what recovery command is appropriate.