Stop a Docker Container Safely with docker kill

You will finish with a repeatable way to target one or more running containers, send the right signal, and confirm what happened. The examples use Docker CLI 29.8.1 from the docker-ce-cli package version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need a shell, the Docker CLI, and access to the Docker daemon. This guide changes container state: a signal can stop a service, discard in-memory work, or trigger an application-specific action. Start with a harmless inspection and keep a recovery plan for anything that matters.

1. Check the installed command

Confirm the binary, package version and option syntax first. These are ordinary read-only commands. They do not need sudo:

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ dpkg-query -W -f='${Package} ${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble
$ docker kill --help
Usage:  docker kill [OPTIONS] CONTAINER [CONTAINER...]

Kill one or more running containers

The local manpage describes docker kill as an alias for docker container kill. The two spellings use the same option, -s or --signal. Keep the long form in scripts when clarity matters:

$ docker container kill --help
Usage:  docker container kill [OPTIONS] CONTAINER [CONTAINER...]

If the version or path differs, read that installation's help before copying examples into automation. The Docker daemon must also be reachable, otherwise even a correctly formed command will fail before it signals anything.

2. Identify the exact running container

List running containers without changing them:

$ docker ps
CONTAINER ID   IMAGE          COMMAND        CREATED        STATUS         PORTS     NAMES
8f4a2c1d9e10   example:1.0    "./server"    12 minutes ago Up 12 minutes            demo-server

Your columns and values will differ. The useful target fields are the full or shortened container ID and the name. Docker accepts a container ID, an ID prefix, or a name. Prefer a name only after checking the current list, because names can be reused after a container is removed.

Checkpoint: write down the exact target and confirm its status is running. For a narrower view:

$ docker ps --filter name='demo-server' --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
CONTAINER ID   NAMES        STATUS
8f4a2c1d9e10   demo-server  Up 12 minutes

Do not infer a target from a partial visual match when several containers have similar names. Resolve the complete list first. A permission error here is a Docker access problem, not a reason to guess or to add sudo blindly.

3. Understand the default before sending it

With no signal option, Docker sends SIGKILL to the container's main process. This normally terminates the container immediately. It does not give the application a chance to flush buffers, close files cleanly, or finish a transaction.

For the deliberately named example target, the command is:

$ docker kill demo-server
demo-server

Docker commonly prints the target name and returns status zero when the request succeeds. The output is acknowledgement of the Docker operation, not proof that the service completed its own cleanup. A non-zero status means you should inspect the error and target before retrying.

4. Verify that the container stopped

Ask for the target in the running list:

$ docker ps --filter name='demo-server' --format '{{.ID}} {{.Names}} {{.Status}}'
$

No output means the name is no longer present among running containers. To distinguish a stopped container from one that was removed, list all containers:

$ docker ps -a --filter name='demo-server' --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
CONTAINER ID   NAMES        STATUS
8f4a2c1d9e10   demo-server  Exited (137) 15 seconds ago

Exit status 137 commonly reflects a process killed by signal 9, because shells report 128 plus the signal number. Treat that value as a useful clue, not as a complete audit trail: inspect the container logs and host events when the reason matters. The stopped container remains available for inspection unless another process removes it.

Recovery depends on what you intended. To start the same stopped container again, use docker start demo-server after checking that its data and dependencies are ready. This is a state-changing command, so do not use it as an automatic undo in a failed incident response. If the container was managed by Compose, systemd or another orchestrator, restore it through that owner instead.

5. Send a selected signal instead

Use --signal when the main process understands a less destructive signal. Docker accepts names such as SIGHUP or HUP, and numeric signal values. The official reference gives SIGHUP as an example:

$ docker kill --signal=SIGHUP demo-server
demo-server
$ docker ps --filter name='demo-server' --format '{{.Names}} {{.Status}}'
demo-server Up 15 minutes

A successful signal request does not mean the container will stop. SIGHUP is often handled as a reload request, so the main process may continue running. Verify the result and inspect the application's logs. Use a signal that the image's entrypoint and main process document; an unhandled signal can still terminate the service.

These forms are equivalent in Docker:

$ docker kill --signal=SIGHUP demo-server
$ docker kill --signal=HUP demo-server
$ docker kill --signal=1 demo-server

Do not assume that a signal reaches the program you think it does. With shell-form ENTRYPOINT or CMD, /bin/sh -c can be PID 1 and may not pass Unix signals to its child. If graceful reload or shutdown is important, check the image definition and process tree before relying on docker kill.

6. Handle multiple targets carefully

The syntax accepts one or more containers:

$ docker ps --format '{{.Names}}'
demo-web
demo-worker
$ docker kill --signal=SIGTERM demo-web demo-worker
demo-web
demo-worker

Resolve the list first, then paste the names explicitly. Avoid an unreviewed command substitution such as docker kill $(docker ps -q) on a shared host: it turns a broad inventory into a destructive action and can include containers you did not intend to interrupt. If a batch is necessary, record the selected IDs and verify the stopped set afterwards with docker ps -a.

7. Diagnose the common failures

If Docker says the container is not found, rerun docker ps -a and check spelling, context and whether another tool renamed or removed it. If it says the container is not running, there is nothing for docker kill to signal; inspect its status and logs instead.

If the client cannot connect to the daemon, check the Docker service and the active Docker context according to your host's operating procedure. Do not fix a daemon or context problem by sending signals to a similarly named container on another host. If access is denied, use the approved Docker group or administrative route for that system. Adding sudo can select a different configuration and context, so verify the target again after elevation.