Detener un contenedor con Docker no elimina la instancia: solicita que el proceso principal termine y conserva el contenedor para poder revisarlo o iniciarlo de nuevo. El comando habitual es docker stop. Entender la señal y el tiempo de espera ayuda a cerrar servicios sin cortar de golpe operaciones en curso.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Qué hace docker stop
Docker envía al proceso principal la señal de parada configurada para el contenedor. Normalmente es SIGTERM, aunque la imagen puede declarar otra con STOPSIGNAL o el contenedor puede tener otra señal configurada. La aplicación dispone del tiempo de gracia para cerrar conexiones y guardar su estado; si no termina antes del plazo, Docker la fuerza con SIGKILL.
El resultado es un contenedor detenido, normalmente con estado exited. Sus datos de la capa escribible y los volúmenes siguen asociados a la instancia; detener no equivale a borrar. Una política de reinicio puede iniciar el contenedor otra vez según su configuración.
Sintaxis y opciones principales
docker stop [opciones] CONTENEDOR [CONTENEDOR...]| Opción o comando | Función | Cuándo utilizarlo |
|---|---|---|
| docker stop NOMBRE | Solicita la parada ordenada del contenedor. | Opción normal para detener un servicio. |
| –timeout SEGUNDOS | Ajusta el periodo de gracia de esta operación. | Cuando la aplicación necesita más tiempo para cerrar. |
| –signal SEÑAL | Envía la señal indicada en vez de la señal configurada. | Solo si el proceso documenta otra señal de apagado. |
| docker kill | Envía SIGKILL por defecto, sin esperar el cierre normal. | Último recurso si la instancia no responde. |
| docker pause | Suspende temporalmente los procesos. | Pausa breve cuando no se quiere finalizar el contenedor. |
| docker compose stop | Detiene los contenedores de servicios Compose y los conserva. | Parar un proyecto Compose sin retirarlo. |
Detener una instancia y comprobar el estado
Antes de detener, identifica el contenedor por nombre, imagen y estado. En este ejemplo el contenedor stop-demo es una instancia de laboratorio; las consultas posteriores permiten confirmar que se detuvo y revisar por qué si no lo hizo.
docker run --detach --name stop-demo nginx:alpine
docker ps --filter name=stop-demo
docker stop stop-demo
docker ps -a --filter name=stop-demo
docker inspect --format "Status={{.State.Status}} ExitCode={{.State.ExitCode}}" stop-demoLa llamada simple usa el tiempo de espera predeterminado del daemon o del contenedor. Si un servicio requiere un cierre más lento, aumenta el plazo de forma explícita. En versiones recientes se recomienda –timeout; –time se conserva por compatibilidad, pero está obsoleto.
docker stop --timeout 30 stop-demoAumenta el plazo solo si la aplicación necesita más tiempo real para cerrar. La señal procede de la configuración de parada de la imagen o del contenedor; no cambies esa señal sin confirmar que el proceso sabe gestionarla.
Stop, kill, pause y restart no son lo mismo
docker stop intenta un cierre ordenado con espera. docker kill envía SIGKILL de manera inmediata por defecto y no deja ese periodo para finalizar tareas. docker pause congela temporalmente los procesos sin cerrarlos. docker restart combina una parada y un nuevo inicio, por lo que también necesita gestionar el cierre.
docker pause stop-demo
docker unpause stop-demodocker pause congela temporalmente los procesos y docker unpause los reanuda; no realiza un apagado ni solicita que la aplicación cierre sus datos. Para reiniciar una instancia existente con una parada previa, docker restart aplica el mismo principio de cierre ordenado y nuevo arranque.
Cuándo recurrir a docker kill
Utiliza docker kill solo cuando el contenedor no responde a la parada ordenada o necesites terminarlo de inmediato. Sin especificar una señal, envía SIGKILL, que no permite a la aplicación completar el cierre ni guardar el estado pendiente. Confirma el nombre o ID y revisa el efecto antes de ejecutarlo.
docker kill stop-demoSi necesitas un apagado normal, vuelve a docker stop. En una aplicación que no responde, investiga después el estado y los logs para localizar la causa del bloqueo.
Qué ocurre con el proceso y los datos
La señal llega al proceso principal del contenedor. Para que el apagado sea limpio, la aplicación debe recibirla y tener tiempo para cerrar archivos, conexiones o transacciones. Si se usa una forma shell de ENTRYPOINT o CMD que no reenvía señales correctamente, el ejecutable puede no recibir la señal esperada.
La parada no borra el contenedor ni sus volúmenes. Si la aplicación no terminó como esperabas, inspecciona los mensajes del proceso y su estado antes de reiniciarla; volver a iniciarla no corrige un fallo de configuración o de datos.
docker logs --tail 100 stop-demo
docker inspect stop-demo --format "StopSignal={{.Config.StopSignal}} Status={{.State.Status}} ExitCode={{.State.ExitCode}}"
docker ps -a --filter status=exitedErrores frecuentes al detener contenedores
- Se usa docker kill para todo: la señal por defecto es SIGKILL y no permite el cierre ordenado que intenta docker stop.
- Se interpreta detenido como eliminado: docker stop conserva la instancia. Para iniciarla otra vez se puede utilizar docker start.
- El servicio vuelve a arrancar: revisa la política de reinicio y si el servicio lo gestiona Docker Compose, systemd u otra herramienta.
- El contenedor no termina dentro del plazo: comprueba si el proceso principal recibe y gestiona la señal; ajusta el plazo solo si necesita tiempo real para cerrarse.
- Se detiene el nombre equivocado: lista los contenedores y confirma el nombre o ID antes de operar; no uses selecciones masivas a ciegas.
Lecciones relacionadas del curso Docker
- Cómo realizar un apagado limpio: entiende cómo la aplicación debe responder a la señal de parada.
- Cómo reiniciar contenedores Docker: compara la parada seguida de un nuevo inicio.
- Cómo investigar un contenedor detenido: analiza estado, código de salida y logs.
- Cómo ver logs de un contenedor Docker: consulta los mensajes que emitió el proceso.

