docker stop hangs, or the container will not stop or stays down
docker stop takes about 10 seconds every timeShort answer
docker stop sends SIGTERM to the main process and waits 10 seconds before SIGKILL. A container that always takes the full ten seconds has a main process that never receives or never handles SIGTERM. Use exec-form CMD, add --init, or set the right stop signal.
Fix it fast
1Find out which cause you have
Check what the container runs as its main process and how long a stop takes.
docker inspect --format '{{.Config.Cmd}} {{.Config.Entrypoint}} {{.Config.StopSignal}}' <container> time docker stop <container>2Match what you see, then jump to its fix
- 1
The command in docker inspect is written as /bin/sh -c ...Shell-form CMD or ENTRYPOINT hides the app from the signalFix - 2
docker stop always takes the full timeout, and the app logs nothing at shutdownThe app ignores SIGTERM or needs more time to shut downFix - 3
docker kill returns the name, but docker ps still shows UpYou sent a signal that does not end the processFix - 4
It is back up after the Docker daemon restartsThe container is restarted by its restart policyFix
- 1
What does the error look like?
docker stop takes about 10 seconds every timedocker kill sends a signal and the container keeps running
Cause 1 of 4
Shell-form CMD or ENTRYPOINT hides the app from the signal
1Check
Shell form runs your program as a child of /bin/sh -c. The shell does not pass signals on, so your program never sees SIGTERM and Docker waits for the timeout.
docker inspect --format '{{json .Config.Cmd}}' <container>2Fix
Write CMD and ENTRYPOINT in exec form, a JSON array, so the program is PID 1. In a start script, finish with exec so the shell replaces itself.
# Dockerfile
CMD ["node", "server.js"]
# entrypoint.sh
exec node server.js3Verify
Rebuild, start, and time the stop.
docker build -t my-app . && docker run -d --name my-app my-app
time docker stop my-appConfirmed by docs.docker.com
Cause 2 of 4
The app ignores SIGTERM or needs more time to shut down
1Check
By default the main process gets SIGTERM, then SIGKILL after 10 seconds on Linux. If the app does not react to SIGTERM, Docker waits out the timeout. An app that needs longer than 10 seconds to close connections and flush data hits the same wall.
docker inspect --format '{{.Config.StopSignal}}' <container>2Fix
Run with --init, which makes an init process PID 1 and forwards signals. Give the container a longer grace period with --stop-timeout, or set the signal the app does handle.
docker run -d --init --stop-timeout 30 --name my-app my-app
# or in the Dockerfile
# STOPSIGNAL SIGINT3Verify
docker stop returns well inside the grace period.
time docker stop my-appConfirmed by docs.docker.com
Cause 3 of 4
You sent a signal that does not end the process
1Check
docker kill sends SIGKILL by default. A different signal given with --signal may not terminate the main process; SIGHUP often leaves it running.
docker ps --filter name=<container>2Fix
Use plain docker kill, or docker stop with a longer timeout, instead of a custom signal.
docker kill <container>3Verify
The container is no longer listed as running.
docker ps -a --filter name=<container>Confirmed by docs.docker.com
Cause 4 of 4
The container is restarted by its restart policy
1Check
A container you stopped by hand ignores always until the daemon restarts or you start it again. With unless-stopped, a hand-stopped container stays down even after a daemon restart.
docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' <container>2Fix
Change the policy so a deliberate stop is kept.
docker update --restart unless-stopped <container>3Verify
Stop the container and restart the Docker service. It stays down.
docker ps -a --filter name=<container>Confirmed by docs.docker.com
How do I stop it coming back?
- Write CMD and ENTRYPOINT in exec form.
- Handle SIGTERM in the app: stop accepting work, flush, then exit.
- Add --init for images that start several processes, so an init process forwards signals.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
A Docker container keeps restarting and never stays up
docker ps --filter status=restarting lists the container
A container restarts forever when its main process exits and a restart policy starts it again.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix