How to Restart a Docker Container (and When Restart Is Not Enough)
Updated July 27, 2026
docker restart <container-name>: it sends SIGTERM, waits 10 seconds (change with -t), SIGKILLs if needed, then starts the container again. A restart keeps the same container: same image, env, mounts, and writable filesystem layer. It will not pick up a new image or changed Compose config: that requires recreating the container (docker compose up -d). For automatic recovery, set a restart policy like --restart unless-stopped.docker restart <container-name>Step 1: restart one or more containers
docker restart is stop-then-start in one command. The -t/--time flag controls how long the engine waits after SIGTERM before escalating to SIGKILL: raise it for apps that need time to flush state. Multiple container names can be passed at once.
docker restart <container-name>
docker restart -t 30 <container-name> # 30s grace instead of 10
docker restart api worker schedulerStep 2: restart vs stop/start vs recreate
restart and stop/start are equivalent in outcome: same container resumes with the same configuration and writable layer. Recreation (docker rm + docker run, or docker compose up -d) builds a fresh container and is required for anything configuration-shaped: a new image version, changed env vars, different port mappings or mounts. The most common Docker troubleshooting mistake is restarting a container and expecting it to run a newly pulled image: it never will.
# picks up a new image / changed config — restart does NOT:
docker pull myapp:1.5
docker stop api && docker rm api
docker run -d --name api ... myapp:1.5
# or with Compose, simply:
docker compose up -dStep 3: set a restart policy for automatic recovery
Restart policies make the engine restart containers without you: no (default), on-failure[:max-retries] (only on non-zero exit), always, and unless-stopped. The difference between the last two shows up at daemon boot: always resurrects containers even if you had stopped them manually; unless-stopped respects a manual stop. For long-running services, unless-stopped is usually what you want. Policies apply to existing containers via docker update.
docker run -d --restart unless-stopped --name api myapp:1.5
docker update --restart unless-stopped api
docker inspect -f "{{.HostConfig.RestartPolicy.Name}}" apiStep 4: restarting Compose services
docker compose restart bounces service containers but deliberately does not re-read the compose file: edits to environment, ports, or image are ignored. To apply compose file changes, run docker compose up -d, which recreates only the services whose configuration actually changed.
docker compose restart # all services, no config reload
docker compose restart api # one service
docker compose up -d # apply compose file changesWhen a container keeps needing restarts
A container you restart daily has an unfixed root cause. Check docker logs for the crash reason, docker inspect for the exit code and OOMKilled flag, and docker events for a restart-loop timeline. A restart policy plus a real fix beats a cron job full of docker restart, and if the process inside hangs without exiting, pair a healthcheck with an autoheal pattern rather than blind scheduled restarts.
docker inspect -f "{{.State.ExitCode}} {{.State.OOMKilled}}" <container-name>
docker events --filter container=<container-name> --since 1hRestarts are where root causes go to hide: a restart makes the symptom vanish while the bug survives. When AI agents handle operations, unsupervised restart-as-remediation can paper over real failures at machine speed. Nexus records every remediation action an agent takes, so a service that an agent has quietly restarted eleven times this week shows up as a pattern in the audit trail instead of staying invisible because the dashboards went green each time.
Explore Swfte NexusCommon questions
- Does docker restart pick up a new image?
- No. A restarted container keeps the image it was created from, even if you pulled a newer tag. Picking up a new image always means recreating the container: docker rm and docker run, or docker compose up -d after a pull.
- What is the difference between --restart always and unless-stopped?
- They behave identically on crashes. The difference is after a manual docker stop plus a daemon restart (or host reboot): always starts the container again anyway; unless-stopped leaves it stopped because you stopped it deliberately.
- Does restarting a container delete its data?
- No: restart (and stop/start) preserves the container's writable layer and volumes. Data loss happens on recreation: the writable layer is discarded with docker rm, which is exactly why anything worth keeping belongs in a volume or bind mount.
- How do I restart all running containers at once?
- docker restart $(docker ps -q) restarts everything currently running. Use it sparingly: it ignores dependency order, so apps may briefly fail to reach databases that are still coming up. Compose handles ordering better via depends_on with health conditions.
- Why did my container restart by itself?
- Either the process exited and a restart policy (always, unless-stopped, on-failure) brought it back, or the daemon/host restarted with live-restore disabled. docker inspect shows RestartCount and the last exit code; docker events gives the timeline.