To restart a Docker container, run docker restart CONTAINER with the name or ID. That’s the whole command. It stops the container and starts it again in one go, and the container ID, writable layer, and volumes stay exactly as they were.
Most people reach for it when a service hangs or a process slowly eats memory. Sometimes it’s just to make a container notice an edited file on a bind mount.
Docker documentation (2026) sets the graceful shutdown wait before SIGKILL at 10 seconds for Linux containers and 30 seconds for Windows containers, and the -t flag overrides both.
What Is a Docker Container Restart?
Think of docker restart as stop plus start on the same container. The ID, the name, and the configuration carry over untouched.
It works on running containers and on ones that already exited. Docker Engine sends the stop signal, waits, and boots the same container back up.
Compare that with docker run, which builds a brand new container from an image with a new ID and a fresh writable layer. A restart keeps the old writable layer and only replaces the main process.
A restart acts on an existing Docker container, so nothing about the container definition changes. Behind the CLI, dockerd hands the request to containerd, and runc launches the process again.
The Docker image behind the container stays untouched. A restart never pulls a newer image.
How Do You Restart a Docker Container From the Command Line?
The full syntax is docker restart [OPTIONS] CONTAINER [CONTAINER...], so one call accepts several targets. Docker CLI prints each name back once the restart completes.
- List containers with
docker psfor running ones ordocker ps -ato include exited ones. - Copy the container name or the container ID (a shortened ID works).
- Run
docker restart my_container. - Run
docker psagain and check that the STATUS column shows a fresh uptime.
The Docker cheat sheet keeps the related commands in one place.
Restart Multiple Containers
List every target after the command, like docker restart web api db. Docker CLI works through them in the order given, which matters when the API can’t boot until the database is up. Put the database first.
Restart All Running Containers
Feed the ID list from docker ps into the command with docker restart $(docker ps -q). The -q flag prints IDs only, and exited containers stay untouched because docker ps skips them.
Everything running restarts at once, including containers nobody meant to touch. On a shared host, run docker ps first and look at what’s actually there.
What Happens Inside a Container During a Restart?
Docker sends SIGTERM to PID 1, waits for the timeout to run out, sends SIGKILL if the process is still alive, and then starts the container again. On Linux the graceful shutdown window defaults to 10 seconds.
SIGTERM and SIGKILL Sequence
The stop signal (SIGTERM unless configured otherwise) reaches PID 1 first. Docker then waits out the timeout, and SIGKILL ends whatever is still running. Only after that does the container come up again with the same configuration.
PID 1 has to handle SIGTERM for a graceful shutdown, and this is where people get bitten. A shell-form ENTRYPOINT runs the app as a child of /bin/sh, and the shell does not forward the signal. So the app never hears it.
Exec-form ENTRYPOINT fixes that. An init process such as tini also forwards signals to the app.
A Dockerfile STOPSIGNAL instruction changes the first signal, and docker restart -s SIGINT overrides it for a single call. Restart follows the same signal path as stopping a container by hand.
docker kill skips the grace period and sends SIGKILL right away, so it’s the wrong tool for a clean restart.
The Timeout Option
Docker documentation (2026) sets the default stop timeout at 10 seconds for Linux containers and 30 seconds for Windows containers.
The -t (--timeout) flag changes the wait per call. Running docker restart -t 30 my_container gives a database 30 seconds to flush writes before SIGKILL. Passing -t -1 waits indefinitely, and --stop-timeout at container creation sets a default for that one container.
What Data and Settings Survive a Restart?
The container ID, writable layer, volumes, bind mounts, environment variables, port mapping, and network attachments all survive. Process memory, in-memory caches, open connections, and unflushed buffers don’t, because the main process is new.
Files in the writable layer persist through a restart. They disappear when the container is removed.
Named volumes sit outside the container filesystem, and where Docker stores volumes on the host decides how easy backups are.
One catch: a restart does not apply edits to environment variables, ports, or the image. Those settings are fixed when the container is created.
The numbers worth remembering (Docker documentation, 2026) are the 10-second default stop timeout on Linux and 30 seconds on Windows. A restart policy also needs the container to run for 10 seconds before it kicks in, and Docker offers 4 policy values: no, on-failure, always, and unless-stopped.
Which Restart Method Fits Your Setup?
The Docker CLI covers single hosts and scripts. Compose projects have their own restart command, Docker Desktop suits local development, Portainer gives teams a web UI, and the Docker Engine API handles automation.
| Method | Best for | Scope | Requires |
|---|---|---|---|
| Docker CLI | Scripts, servers | Any container | Shell access |
| Docker Compose | Multi-service apps | Services in one project | Compose file |
| Docker Desktop | Local development | One container per click | Desktop install |
| Portainer | Team dashboards | Any managed host | Portainer running |
| Engine API | Automation | Any container | API access |
The CLI is the fastest path. It works over SSH and it’s easy to script, though you do need shell access to the host.
Docker Compose restarts services by name, and --no-deps skips the ones that depend on it. The catch is that it ignores edits to compose.yml. The Docker Compose reference says a plain restart reflects none of those changes, environment variables included.
Docker Desktop has a restart button in the Containers view, so there’s no command to remember. It only covers your local machine, though.
Portainer lets you restart from a browser across several hosts. You pay for that with one more service to run and patch.
The Engine API exposes POST /containers/{id}/restart, which fits CI jobs and custom tooling. It needs authenticated access to the daemon socket.
Honestly, the plain CLI handles most cases. A GUI adds little unless the team already runs one.
Should You Restart, Stop and Start, or Recreate the Container?
Use docker restart when the configuration stays the same. Use docker stop then docker start when something has to happen in between. After any change to the image, environment variables, or port mapping, recreate the container.
Restart is one command on the same container with the same configuration. The downside is that you get no window to act while the container is down.
Stop then start gives you that window, so you can edit a bind-mounted file or copy data out while nothing is running. It takes two commands, and the container stays down if you forget the second one.
Recreating (docker rm then docker run, or docker compose up -d) applies a new image, new env vars, and new ports. The price is the writable layer, which is gone unless the data sits on a volume.
Recreating means building a new container, and creating a Docker container starts from the image, not the old writable layer.
In practice it comes down to a few cases. A hung app or a memory leak gets a restart, and so does a changed config file on a bind mount. A changed env var, port, or image tag needs a recreate. If you want a cold, inspectable stop, stop the container, do your work, then start it.
docker compose up -d recreates only the services whose configuration changed.
How Do Restart Policies Work?
A restart policy tells dockerd when to restart a container automatically. Docker has 4 policy values: no, on-failure[:max-retries], always, and unless-stopped. The default is no.
| Policy | Restarts when | After a manual stop |
|---|---|---|
| no | Never | Stays stopped |
| on-failure | Exit code is non-zero | Stays stopped |
| always | Container stops for any reason | Returns after a daemon restart |
| unless-stopped | Container stops, unless stopped by hand | Stays stopped, even after a daemon restart |
The on-failure policy takes an optional retry cap, such as on-failure:5. It does not restart the container when the daemon restarts.
Set a policy at creation with docker run -d --name redis --restart unless-stopped redis. Change a live container with docker update --restart unless-stopped redis.
Docker documentation (2026) states that a policy takes effect only after the container runs for at least 10 seconds, which prevents a container that never starts from looping.
Policies that depend on a restart of the daemon need dockerd running again first. The steps for bringing the Docker daemon back up differ between Linux hosts and Docker Desktop.
Docker recommends restart policies over process managers. Combining a policy with a host-level manager such as systemd creates conflicts.
Restart policies apply to containers only. Swarm services use the restart flags of docker service create instead.
How Do You Verify a Container Restarted Correctly?
A restart worked when the container ID is unchanged, the uptime is new, and the logs show a clean boot. Docker gives you docker ps, docker inspect, docker logs, and docker events to check each of those.
Every check here needs a reachable daemon, so confirming that Docker itself is running comes first when commands hang.
Start with docker ps. Right after the restart, STATUS reads something like “Up 8 seconds” and the container ID matches the earlier one.
Then run docker inspect. State.Status should read running, State.StartedAt shows the new start time, and RestartCount tracks automatic restarts under a restart policy.
For output, docker logs --since 1m my_container prints only what was written after the restart, and --tail 50 gives you the last 50 lines. If you want the full lifecycle sequence, docker events --filter container=my_container --since 5m lists the kill, die, stop, start, and restart events for that container.
Docker documentation (2026) states that docker events returns only the last 256 events, so add a container filter and a –since window on busy hosts.
A container with a HEALTHCHECK adds one more signal. The health status in docker ps moves from starting to healthy once the check passes, and a container stuck on unhealthy needs the health log from docker inspect.
Why Does a Container Keep Restarting or Exit With Code 137?
A container that keeps restarting is in a crash loop, where the restart policy revives a process that just exits again. Exit code 137 equals 128 plus 9, which means SIGKILL, sent either after the stop timeout expired or by the Linux OOM killer.
Crash Loops From Restart Policies
The docker ps STATUS column shows Restarting instead of Up when a loop is running. RestartCount in docker inspect climbs with every cycle.
- Run
docker logs --tail 50 my_containerand find the startup error. - Read the last exit code with
docker inspect --format '{{.State.ExitCode}}' my_container. - Break the loop with
docker update --restart no my_container. - Fix the cause, then recreate or start the container.
The usual culprits are a missing environment variable, a port already taken on the host, or an ENTRYPOINT pointing at a file that doesn’t exist.
Exit Code 137 and OOM Kills
Docker documentation (2026) shows the sequence in its docker events examples. You get a kill event with signal=15, a second kill with signal=9, then a die event with exitCode=137. A process that dies from SIGTERM alone reports exitCode=143.
Two different causes produce the same code, and the table separates them.
| Cause | Signals | Confirm by |
|---|---|---|
| Stop timeout expired | SIGTERM, then SIGKILL | docker events shows kill signal=15, then signal=9 |
| OOM kill | SIGKILL from the kernel | State.OOMKilled is true, oom event present |
| Manual docker kill | SIGKILL only | kill event with signal=9 and no earlier signal=15 |
cgroups enforce the memory limit set with -m, and the kernel kills processes inside the container when usage crosses it.
Docker adjusts the OOM priority of dockerd so it is less likely to be killed, but leaves containers unadjusted, so a container is more likely to die before the daemon does. Setting --oom-kill-disable without -m puts host processes at risk, so don’t.
Unhealthy Containers
A restart policy reacts to an exit, not to a failing health check. So a container can sit there unhealthy for hours and nothing will touch it.
docker ps shows (unhealthy) next to the uptime, and the health log in docker inspect holds the output of the recent HEALTHCHECK runs. Restart once, then compare the health log before and after.
A transient cause, such as a stalled connection pool, clears after a restart. A check that fails again within its first runs points to the image or the configuration.
When Does Restarting a Container Not Work?
Restarting fails when the fault sits in the image, the configuration, or the memory limit, because the container returns with the same defect. Each case needs its own fix.
| Situation | Symptom after restart | Use instead |
|---|---|---|
| Env var, port, or image tag changed | Old value still active | Recreate the container |
| Broken entrypoint or bad image | Same exit code on every start | Fix the image or pin the previous tag |
| Memory limit too low | Exit code 137 returns later | Raise -m or fix the leak |
| Stateful service, short timeout | Unflushed writes lost | Longer -t value |
| Corrupted data on a volume | Same errors after boot | Restore from backup |
A restart reuses the image, so a defective build fails again on every start.
Pinning the previous tag works like rolling back the deployment, and it needs a recreate, not a restart.
Restarting an OOM-killed container frees memory for a while and hides the leak. The kill comes back once usage climbs to the limit again.
SIGKILL gives the application no chance to flush buffers. A database recovers from its journal on the next boot and drops whatever was unflushed.
Named volumes survive restarts, and so does any corruption inside them.
Restart once. If the same error comes back, stop restarting and read the container logs.
FAQ on How To Restart A Docker Container
How do you restart the Docker daemon?
Run sudo systemctl restart docker on systemd hosts. Running containers stop with dockerd unless live-restore is enabled.
Containers with an always or unless-stopped restart policy start again once the daemon is back.
How do you restart a service in Docker Swarm?
Run docker service update --force SERVICE. Swarm replaces the tasks one by one under the update settings, so the service keeps answering while each replica restarts.
docker restart on a single task container works only on the node that runs it.
How do you restart a container over SSH?
Pass the command through ssh with ssh user@host docker restart my_container. The remote user needs access to the Docker socket.
A docker context with an ssh:// endpoint points the local Docker CLI at the remote dockerd.
How do you fix a permission denied error when restarting a container?
The error means the current user cannot reach the Docker socket. Prefix the command with sudo, or add the user to the docker group and log in again.
Membership in that group gives root-level access to the host.
Can you restart a container without downtime?
A single container always has a gap between stop and start. Zero downtime needs 2 or more replicas restarted one at a time.
A load balancer in front of the replicas routes traffic to the ones still running.
What Should You Fix First in How To Restart A Docker Container?
If a restart fails twice in a row, work through the checks in a fixed order. Read the container logs and the exit code, then look at RestartCount and the health check status. Recreate the container with the corrected configuration only after that. Each step rules out one cause, and a restart just repeats any fault you left in place.
Logs first, recreate last. Logs cost nothing and change nothing, while a recreate discards the writable layer.
A recreate applies new settings but drops every file written outside a volume, so move that data first.
Docker documentation was checked in September 2026, and a later Docker Engine release that changes restart policy rules alters this order.
Once the container runs again, getting a shell inside the container is the next step for inspecting files and processes.
- How to Turn On Dark Mode in Notepad++ (Built-In, No Plugin) - October 3, 2026
- PostgreSQL Cheat Sheet - October 2, 2026
- How to Repair a Corrupt SQL Server Database Without Any Data Loss - October 2, 2026
