Most people type docker stop, watch the container name echo back, and move on. A fair bit happens in between, and it decides whether the data inside that container survives the shutdown.
Docker’s own reference sets the default wait at 10 seconds before SIGKILL takes over for Linux containers, stretched to 30 seconds for Windows containers (Docker Docs, 2026).
What Is the Docker Stop Command
It ends a running container by sending a termination signal first and forcing a kill only if the process ignores it.
Developers and sysadmins run it against the Docker Engine, on a single host or inside a bigger orchestration setup, whenever a workload should wind down cleanly instead of crashing.
The command lives in the Docker CLI, right next to docker run and docker ps. It targets the container’s main process. The image and the files sitting inside the container aren’t its concern.
Stopping a container doesn’t delete it. The container and its writable layer stay on disk, ready to come back with docker start, and attached volumes and the underlying image are left alone too.
In lifecycle terms, a stopped container sits between running and removed.
The request goes to the Docker daemon, part of the Docker Engine, before it reaches the process running inside the docker container itself.
Docker Stop vs Docker Kill: What’s the Difference
Stop sends a termination signal and waits. Kill ends the process immediately, no waiting period at all.
That gap changes how safe each one is against a live workload.
With docker stop, SIGTERM goes out first, so the application gets a chance to close files, flush buffers and exit on its own terms. That makes it the better fit for databases and queues, and it matches how orchestrators shut services down. The downside is speed. If the process ignores the signal, you sit through the whole grace period and the container still ends in a forced kill.
docker kill sends SIGKILL by default, and the kernel enforces it instantly. The process can’t catch it or delay it. That’s handy when a container is frozen or the daemon needs resources back fast, but nothing gets cleaned up. Corrupted writes and half finished transactions are the price.
When to Use Docker Kill Instead
Reach for kill when a container is genuinely stuck, or when it’s blocking a deployment that has to move forward.
- A container sitting in an infinite loop with no exit path
- A process that ignores signals because nobody wrote a signal handler for it
And if waiting even 10 seconds isn’t an option, that counts too.
Outside of those cases, docker stop stays the safer default for day to day container management.
How the Docker Stop Timeout and Signal Sequence Work
One signal goes out, the daemon waits a fixed number of seconds, and if the container still hasn’t exited, a second signal follows. The wait is what people usually mean by the grace period.
On Linux the default is 10 seconds, and on Windows it’s 30 seconds (Docker Docs). The first signal is SIGTERM, unless the image sets a different STOPSIGNAL or the container was created with --stop-signal. SIGKILL only arrives once the timeout expires.
The daemon handles the countdown, not the Docker CLI itself. Docker’s reference also says these numbers only apply when no custom value was set at container creation with --stop-timeout.
Some applications need more room than the default window. Database and integration platforms with large write buffers are the usual suspects, since closing their connections cleanly takes a while.
Docker Stop Command Syntax and Options
The base form is docker stop followed by a container name or ID. Flags like -t change the grace period, and that’s about all there is to it.
- Run
docker stop CONTAINERusing either the container name or its ID, full or shortened - Add -t or –timeout followed by a number to change the grace period from its default (older guides and documentation call the long form
--time) - Set –timeout -1 if the daemon should wait indefinitely instead of forcing a kill
- Confirm the result with
docker ps -a, which lists the container in an Exited state once it has stopped
A short container ID is usually unique enough on its own. Docker only needs enough characters to tell it apart from the other containers on the same host.
Software AG’s own documentation for its Integration Server says the default 10 second wait is not enough for a graceful shutdown and recommends setting the wait time to at least 30 seconds, more if shutdown services are configured (Software AG documentation).
Which is a pretty good case for the flag existing at all. Everything on this command is optional except the container reference.
Keeping a docker cheat sheet nearby helps when you need to check flags in the middle of a live incident.
How to Stop Multiple Docker Containers at Once
You can pass several container names or IDs to a single docker stop, separated by spaces.
Containers that run several services under a systemd style init need far more than the default window. The docker-systemctl-replacement project documentation advises raising the timeout to at least 100 seconds, because 10 seconds is too short for normal service scripts to bring their applications down completely (docker-systemctl-replacement project documentation).
- Name every target directly, for example
docker stop web app_cache app_worker - Capture everything running at once with
docker stop $(docker ps -q) - If only part of the host should stop, filter first, using
docker ps -qwith a status or label filter - Check the result afterward with
docker ps -ato confirm each one landed in an Exited state
Docker applies the same timeout to every name in that list.
A batch full of slow-to-exit containers takes longer to finish than one that shuts down cleanly. Obvious, but easy to forget when you’re staring at a terminal that hasn’t returned yet.
Stopping Containers With Docker Compose
Compose carries the same stop behavior over to every service defined in one YAML file.
If the tool is new to you, have a look at what Docker Compose actually does before touching the stop command.
Running docker compose stop halts each service’s containers without deleting the containers, networks or volumes that compose created for the project. Give it a service name, as in docker compose stop web, and only that service goes down while the rest of the stack keeps running. Leave the name off and every container in the compose file stops.
Docker’s 2025 State of Application Development report found container usage at 92 percent among IT professionals, against 30 percent across other industries, and 35 percent of all respondents said they work on microservices-based applications (Docker, 2025).
Multi-service applications are why compose exists in the first place. Stopping five or six related services one by one with plain docker stop gets old fast.
Compose follows the same SIGTERM then SIGKILL sequence as docker stop. The grace period comes from the stop\_grace\_period setting in the compose file, or from the -t flag on the command.
Docker Compose Stop vs Docker Compose Down
Compose stop halts containers and leaves them on disk. Compose down removes the containers along with the network compose created for them.
Volumes are the part people get wrong.
| Command | Containers | Networks | Volumes |
|---|---|---|---|
| docker compose stop | Stopped, not removed | Kept | Kept |
| docker compose down | Removed | Removed | Kept unless -v is added |
| docker compose down -v | Removed | Removed | Removed |
Named volumes survive a plain docker compose down. Only the -v flag removes the named volumes declared in the compose file, along with anonymous volumes attached to the containers.
If the images tied to those services need to go as well, add –rmi to the down command. That follows the same logic as clearing out unused docker images by hand.
Use stop if you plan to come back soon. Use down when you want the project reset from scratch.
What Happens to Restart Policies When You Stop a Container
A restart policy tells Docker whether to bring a container back after it stops. There are four of them, and a manual docker stop only gets undone by one, and only when the daemon restarts afterward.
| Policy | After docker stop | After daemon restart |
|---|---|---|
| no (default) | Stays stopped | Stays stopped |
| on-failure | Stays stopped | Not restarted |
| unless-stopped | Stays stopped | Stays stopped |
| always | Stays stopped | Restarts automatically |
Docker’s own reference notes a restart policy only takes effect once a container has stayed up for at least 10 seconds, which keeps a container that fails on startup from looping endlessly.
That 10 second window decides whether a restart policy applies at all. It has nothing to do with the stop timeout covered earlier, even though the number happens to match.
With always, a manual docker stop only holds the container down for now. It comes back the moment the Docker daemon restarts, planned or not, or when someone starts it again by hand.
Docker remembers the manual stop under unless-stopped and keeps the container down through a full daemon restart too.
Docker Container Exit Codes After Stop
Docker reports how a container ended through its exit code, and that number tells you whether the shutdown was clean or forced.
Exit code 0 means the process exited cleanly on its own. After docker stop, that usually means the application caught SIGTERM and finished its shutdown normally. Exit code 143 means SIGTERM terminated the process, the sum of 128 plus signal 15. Exit code 137 means SIGKILL ended it, the sum of 128 plus signal 9.
That 128-plus-signal math is a standard Unix convention and nothing Docker invented. Most container runtimes report a signal death the same way.
To read the result without digging through logs, run docker inspect CONTAINER --format '{{.State.ExitCode}}' and it prints the number directly.
A container that regularly exits with 137 after a plain docker stop is telling you SIGTERM either never reaches the application or is never acted on, so the timeout ran out and SIGKILL finished the job.
Why Docker Stop Fails or Hangs
When docker stop hangs for the full grace period, it almost always traces back to the signal never reaching the process that needed it.
An ownCloud server bug report documented this exactly. The container started Apache through the apachectl shell wrapper, so SIGTERM reached the wrapper but never Apache itself.
With the timeout set to 60 seconds, the container took 60.113 seconds to go from SIGTERM to SIGKILL, then died 0.203 seconds later once SIGKILL landed (owncloud-docker/server GitHub issue tracker).
Apache kept serving healthy checks the entire time it was supposedly shutting down.
The usual causes look like this:
- Shell form CMD or ENTRYPOINT wraps the real process inside /bin/sh, which doesn’t forward signals to its children
- A wrapper script starts the application without exec, so it runs as a child process instead of PID 1
- The application never registered a SIGTERM handler, so the signal gets effectively ignored until SIGKILL arrives
- An application acting as PID 1 without reaping its children leaves zombie processes piling up
- Something else entirely, which is worth ruling out before you blame Docker
Switching to exec form fixes most of these cases. So does adding Docker’s own --init flag, which runs a small process like tini as PID 1. Neither touches application code.
When Docker Stop Does Not Apply
Docker stop works on individual containers running directly under the Docker Engine. Once something else owns the container’s lifecycle, it stops behaving the way people expect.
- Docker Swarm services reconcile their containers back to the declared replica count, so stopping one manually just triggers a replacement. Scale the service down instead, with
docker service scaleordocker service rm - Kubernetes pods go through Kubernetes’ own termination sequence. It sends SIGTERM through the container runtime and tracks its own grace period rather than deferring to a raw docker stop call
- Paused containers have every process suspended at the kernel level after
docker pause, so a signal only takes effect once the container is resumed. Recent Docker Engine versions unpause the container after sending the stop signal, while older ones requiredocker unpausefirst. Running docker unpause before docker stop works on every version - Containers that already exited just return without error if you run docker stop on them. Nothing happens
Kubernetes handling its own shutdown sequence is one of several practical differences between Kubernetes and Docker that are worth understanding before you run production workloads on either.
None of this means the command failed. Something other than the Docker CLI had already made the decision to stop.
FAQ on How To Stop Docker Container
Does Docker Stop Delete the Container
It doesn’t. Docker stop only ends the running process inside the container.
The container, its writable layer and any mounted volumes stay on disk. To remove it, run docker rm after the container has already stopped.
What Is the Difference Between Docker Stop and Docker Pause
Stopping runs the SIGTERM and SIGKILL sequence and ends the container’s process.
Pausing freezes every process inside the container using the kernel’s cgroup freezer. Nothing is terminated and nothing is signaled, and unpausing resumes execution exactly where it left off.
Does Docker Stop Work on a Container Inside a Kubernetes Pod
Not directly. Kubernetes manages pod containers through its own container runtime interface and grace period setting, bypassing the Docker CLI entirely.
Delete or scale the pod instead. A manual docker stop against the node gets overridden by the kubelet.
Can You Set a Custom Timeout for Docker Stop
Yes. The -t or --timeout flag overrides the default grace period for one command.
To make a custom value stick, set –stop-timeout at container creation. Every later docker stop call against that container then uses it automatically.
How Do You Stop a Docker Container by Name or ID
Pass either one directly after docker stop. Names come from --name at creation, or Docker assigns one for you.
IDs work in shortened form, as long as what you type matches only one container on the host. Stopped containers count too, so a prefix that looks unique among running containers can still be ambiguous.
How Do You Stop All Running Containers in One Command
Combine docker ps -q with docker stop, like this: docker stop $(docker ps -q).
The first command lists every running container’s ID, and the second stops each one in turn. If nothing is running, the list comes back empty and docker stop returns an error, because it needs at least one container name or ID.
How Do You Check if a Container Has Stopped Successfully
Run docker ps -a and look for a status of Exited next to the container name.
For scripts that need to confirm shutdown before moving on, docker inspect CONTAINER --format '{{.State.Status}}' prints exited in one line.
What User Permissions Are Needed to Run Docker Stop
You need access to the Docker socket, either through membership in the docker group or root privileges via sudo.
Docker Engine treats socket access as full control, so anyone who can run docker stop can also start, remove or inspect any container.
What Should You Check First When Docker Stop Doesn’t Work?
Start with signal handling. Confirm the application actually receives SIGTERM as PID 1 before you touch anything else.
Restart policy comes next, since always or an orchestrator-managed replica set can undo a stop before anyone notices. After that, check whether Swarm or Kubernetes owns the container at all. Checking in that order beats guessing at random.
Raising the stop timeout buys an application more room to close connections. The catch is that every deployment, rollback and scale-down touching that container now waits longer for the same window.
That trade-off stops paying off once the process never handles SIGTERM at all, since no timeout length fixes a signal nobody catches.
Once the container is down, the natural next step is bringing it back, which is covered separately in the guide on restarting a stopped container.
- MySQL Cheat Sheet - September 30, 2026
- How to Remove Duplicate Lines in Notepad++ (Sorted or Unsorted) - September 29, 2026
- Should Your Engineering Team Still Own the Marketing Website? - September 29, 2026
