You need to take a container down with docker container stop, and you want the app to finish what it is doing first. This guide gives you a repeatable way to stop one or more containers, allow clean-up time, and confirm the result. The examples match Docker 29.8.1, the installed Docker CLI used for this guide.
Warning: stopping a container disrupts service. Requests can fail and in-flight work can be interrupted, so make sure you have selected the right container before pressing Enter.
Start with read-only checks. Ordinary Docker installations allow these commands for members of the docker group or an equivalent setup. If your account is not allowed to talk to the daemon, use sudo only when that is already the normal administration method on this host.
$ docker --version
Docker version 29.8.1, build 4a63305
$ docker container stop --help
Usage: docker container stop [OPTIONS] CONTAINER [CONTAINER...]
Stop one or more running containersThe command also has the shorter alias docker stop. The longer form makes scripts and runbooks clearer, so it is used here. If the version or help output differs, read the installed help before copying a timeout or signal from another machine.
Checkpoint: if docker --version works but the next command reports a daemon or permission error, fix that access problem first. Do not add random flags to the stop command.
List running containers and check both the name and the image. A short ID is also accepted, but a name is easier to review before a disruptive action.
$ docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
abc123def456 example/web "/start-web" 2 hours ago Up 2 hours 8080/tcp web-exampleYour columns and values will differ. Replace CONTAINER_NAME below with an exact value from your own output:
$ CONTAINER_NAME='web-example'
$ docker container inspect -f '{{.Name}} {{.State.Status}}' "$CONTAINER_NAME"
/web-example runningTip: if docker container ls does not list the container, it was not running at the time of the check. Use docker container ls --all to tell a stopped container from a misspelled name. Do not stop a container merely because its name looks familiar.
Once the identity is confirmed, run:
$ docker container stop "$CONTAINER_NAME"
web-exampleHere is what Docker does with that:
SIGTERM unless the image or container selected another.SIGKILL if the process has not exited by then.The local command exposes this behaviour as --signal and --timeout. The output is normally the name or ID of each container that stopped. A zero exit status means the stop request completed. It does not mean that the application flushed every external queue or completed every business operation.
Warning: do not use --signal SIGKILL as a first attempt. It removes the process's opportunity to close files, finish a transaction or flush logs. Use it only when you have accepted that abrupt termination is necessary.
Check the state directly:
$ docker container inspect -f '{{.Name}} {{.State.Status}}' "$CONTAINER_NAME"
/web-example exitedYou can also confirm that it has left the running list:
$ docker container ls --filter "name=^/${CONTAINER_NAME}$"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMESExact formatting varies with the CLI and filters. The useful facts are that the state is no longer running and that the container still exists when inspected. Its logs remain available through docker container logs "$CONTAINER_NAME".
Checkpoint: state exited, container still inspectable, logs still readable.
Use --timeout when the service needs more or less time than its configured default. This example allows 30 seconds:
$ docker container stop --timeout 30 "$CONTAINER_NAME"
web-exampleThe timer begins after Docker sends the selected stop signal. If the process is still alive when the timeout expires, Docker forcibly kills it.
Warning: a timeout of -1 waits indefinitely, which can leave an automation job stuck forever. Reserve it for a process you can monitor and interrupt deliberately.
To see what timeout the container was created with, inspect its configuration without changing it:
$ docker container inspect -f '{{.Config.StopTimeout}} seconds' "$CONTAINER_NAME"
10 secondsA displayed value can vary or be unset depending on how the container was created. On Linux, Docker's daemon default is commonly ten seconds when no container-specific default is configured. An explicit timeout on the stop command is clearer when the shutdown window matters.
The command accepts one or more container names or IDs. Review the complete list first, then pass each item as a separate shell argument:
$ docker container stop web-example worker-example
web-example
worker-exampleWarning: do not build this list from an unreviewed broad filter. A shell expansion or a copied production label can include more services than intended.
For a planned maintenance stop, record the names, run the command, and verify each one:
$ for name in web-example worker-example; do
docker container inspect -f '{{.Name}} {{.State.Status}}' "$name"
done
/web-example exited
/worker-example exitedIf a stop request fails for one container, read the error and check the states individually. Do not assume that every name in the command stopped successfully.
Stopping does not delete the container. If the shutdown was accidental and the application is ready to return, start that same container:
$ docker container start "$CONTAINER_NAME"
web-example
$ docker container inspect -f '{{.Name}} {{.State.Status}}' "$CONTAINER_NAME"
/web-example runningStarting is not a substitute for checking why the service was stopped. Review the logs and any deployment or maintenance record before restoring production traffic. If the container was designed to be recreated by an orchestrator, follow that system's recovery procedure instead of repeatedly starting it by hand.
Recovery: there is no undo for a process that was already killed or for work the application had not persisted. Restore from the application's own queue, transaction log or backup, then restart the container when safe.