DevOps Tutorials, Guides & Best Practices

docker kill sends a signal to the main process of one or more running containers. By default, it sends SIGKILL, which ends the process without a grace period. Use it when a container must stop immediately; for routine shutdowns, use docker stop so the application can handle its stop signal first.

Quick answer: run docker kill CONTAINER for the default SIGKILL, or add --signal to send a different signal. A custom signal is not guaranteed to stop the container because the main process may handle or ignore it.

docker kill my_container

What the Docker Kill Command Does

The docker kill command targets the container’s main process. Docker sends SIGKILL by default, but the --signal option can send a named signal such as SIGTERM, SIGHUP, or SIGINT. Docker also accepts the signal without the SIG prefix or as a number.[1]

SIGKILL is terminal. A custom signal may be non-terminal, so docker kill --signal=SIGHUP my_container can leave the container running if its main process treats SIGHUP as a reload request.

Docker Kill vs. Docker Stop

docker stop and docker kill differ in both signal behavior and waiting time. docker stop sends the container’s configured stop signal, or SIGTERM when no stop signal is configured. It waits for the grace period and then sends SIGKILL if the process has not exited.[2]

Recommended default: use docker stop for normal operations. Use the default docker kill when immediate termination is the intended action, not as the first troubleshooting step.

How to Stop an Unresponsive Container Safely

Use this sequence when a container is unhealthy or unresponsive. Each step produces evidence before the process disappears.

1. Confirm the target and its state. Check the container name, status, and restart policy before sending a signal.
2. Capture the latest logs. Save the failure context if the logs may rotate or disappear after another deployment.
3. Attempt a graceful stop. Give the main process enough time to close connections and flush state.
4. Use docker kill only when immediate termination is required. The default signal is SIGKILL.
5. Verify the final state. Inspect the status, exit code, and any daemon-reported error.
6. Check the restart policy. A container can return after it exits if Docker is configured to restart it.

1. Inspect the Container

docker inspect --format 'status={{.State.Status}} restart={{.HostConfig.RestartPolicy.Name}}' my_containerCode language: JavaScript (javascript)

2. Capture Recent Logs

docker logs --tail 200 --timestamps my_container

Logs may explain why the process stopped responding. Capture them before an emergency termination if they are needed for incident review.

3. Try a Graceful Stop

docker stop --timeout 30 my_container

The timeout is the number of seconds Docker waits after sending the stop signal. If the process remains running when the timeout expires, Docker sends SIGKILL.[2]

4. Send SIGKILL When Immediate Termination Is Required

docker kill my_container

The default command sends SIGKILL to the container’s main process. The container object remains available after the process exits, so you can still inspect it or start it again.

5. Verify the Exit State

docker inspect --format 'status={{.State.Status}} exit={{.State.ExitCode}} error={{.State.Error}}' my_containerCode language: JavaScript (javascript)

Treat the exit code as evidence, not a complete diagnosis. Application logs, daemon events, health checks, and the signal used may all be needed to explain the shutdown.

How to Send a Custom Signal

Use --signal when the application has documented signal behavior. Docker accepts a signal name with or without the SIG prefix, or a supported signal number.[1]

docker kill --signal=SIGTERM my_container
docker kill --signal=TERM my_container
docker kill --signal=15 my_container

These examples request the same signal on Linux. They do not reproduce the full behavior of docker stop because docker kill --signal=SIGTERM sends one signal and does not then send SIGKILL if the process remains running.

Reload an Application with SIGHUP

docker kill --signal=SIGHUP my_container

Some applications use SIGHUP to reload configuration. Others ignore it or exit. Check the application’s own documentation before using a custom signal in production.

Why PID 1 and ENTRYPOINT Matter

Docker sends the signal to the container’s main process. When ENTRYPOINT or CMD uses shell form, the application may run as a child of /bin/sh -c instead of as PID 1. Docker documents that this shell does not pass signals to the child process in this configuration.[1]

Use exec form when the application should receive Unix signals directly. The Dockerfile ENTRYPOINT guide explains the difference between shell form and exec form.

ENTRYPOINT ["/usr/local/bin/my-app"]Code language: CSS (css)

A wrapper script can also forward signals and reap child processes. If the container runs several processes, use a suitable init or supervisor instead of assuming every child will receive Docker’s signal.

Why a Killed Container Starts Again

A restart policy can start the container again after its main process exits. Docker supports no, on-failure, always, and unless-stopped. The exact restart depends on the selected policy, the exit condition, and whether the container was stopped manually.[3]

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' my_containerCode language: JavaScript (javascript)

If the restart is not intended, inspect the policy before repeatedly killing the process. You can update an existing container and then stop it deliberately:

docker update --restart=no my_container
docker stop my_container

For Compose services, change the source configuration as well. Otherwise, the next docker compose up can restore the previous policy. See the Docker Compose restart policy guide for the Compose-specific behavior.

Common Docker Kill Mistakes

• Killing before collecting evidence. Capture logs and state first when the host is stable enough to wait.
• Assuming every custom signal stops the container. A signal such as SIGHUP may be handled without exiting.
• Using docker kill --signal=SIGTERM as a synonym for docker stop. The first sends one signal; the second adds a grace period and forced termination if needed.
• Ignoring PID 1. Shell-form entrypoints can prevent the intended application process from receiving signals directly.
• Ignoring the restart policy. The container may exit correctly and then return because Docker restarts it.
• Deleting the container to solve a process problem. docker kill stops the process but keeps the container object for inspection.

FAQ

The command changes the container’s process state; it does not delete the container, and any configured restart policy still applies.

Sources

• Docker Docs: docker container kill
• Docker Docs: docker container stop
• Docker Docs: Start containers automatically