Restart Docker Containers Without Losing the Timeout

docker container restart looks like a free do-over, but it stops the container and starts it again, and clients lose their connections either way. Allow about ten minutes for a single container, longer if it serves live traffic or needs a health check.

The commands below use Docker CLI 29.8.1 from the installed docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble. Restart does not rebuild the image or recreate the container. Have the container name or ID ready, and use a maintenance window for anything carrying user traffic.

1. Check the command and identify the container

Confirm the installed syntax first. It is read-only and normally needs no elevated privileges:

$ docker container restart --help
Usage:  docker container restart [OPTIONS] CONTAINER [CONTAINER...]

Restart one or more containers

The shorter alias is docker restart. List every container, running or not, so a stopped one is not mistaken for a missing one:

$ docker container ls --all --format 'table {{.Names}}\t{{.Status}}'
NAMES             STATUS
my-web             Up 2 hours
my-worker          Exited (1) 5 minutes ago

Replace my-web below with the exact name or ID from your own output; the first column is the value that matters, the status text is only a snapshot.

Checkpoint: You have selected the intended container and confirmed that restarting it will not interrupt the wrong service.

2. Restart one container with its configured defaults

For the ordinary case, restart it without adding options:

$ docker container restart my-web
my-web

A successful command prints the name or ID and exits with status 0. Check both the status and the recent state transition:

$ printf 'restart status: %s\n' "$?"
restart status: 0
$ docker container ls --filter name='^my-web$' --format 'table {{.Names}}\t{{.Status}}'
NAMES    STATUS
my-web   Up 8 seconds

• The exact uptime will differ on your host.
• A status stuck on Restarting means the main process keeps exiting, or the restart policy keeps starting it again. That first successful CLI response is not proof the application is healthy.
• There is no instant undo. Restart changes runtime state; to return a container to stopped, use docker container stop my-web only when that is what you intend. A later restart will start it again, but it will not restore lost client connections.

3. Give a clean shutdown enough time

Docker sends the container's configured stop signal, then waits for the timeout before forcing the process down. On Linux, the daemon's default is 10 seconds when the container has no configured stop timeout. Give a slow application more time when it needs to flush data or finish requests:

$ docker container restart --timeout 30 my-web
my-web

The short form is -t 30, measured in seconds. The local manpage displays the option default as 0: that is the CLI value meaning Docker should use the container or daemon default, not a promise of an immediate kill. Use an explicit positive value when graceful shutdown time actually matters.

Safety boundary: A larger timeout does not make a broken process healthy, it only delays the forced kill. A timeout of -1 waits indefinitely, which can leave a deployment blocked forever, so use it only when that behaviour is deliberate and monitored.

4. Select a different stop signal only when required

Most containers should use their configured stop signal. If the image or application expects another, pass it explicitly with --signal or -s:

$ docker container restart --signal SIGUSR1 --timeout 30 my-web
my-web

• Docker accepts a signal name such as SIGKILL, or an unsigned number such as 9. Check the application's documentation before changing this.
• The default comes from the image's STOPSIGNAL or the container configuration; if none is set, Docker uses SIGTERM.
• Do not use SIGKILL as a routine shortcut. It removes the application's chance to close files, flush buffers or finish a transaction. If the container ignores the normal signal, diagnose the process and its logs rather than hiding the problem behind a forceful default.

5. Restart several containers deliberately

The command accepts more than one name or ID. Put every target on the same reviewed command line:

$ docker container restart --timeout 30 my-web my-worker
my-web
my-worker

Docker prints each successfully restarted target. Before using this in a production shell script, list the names and record the exit status: a typo, a missing container or a daemon error should stop your follow-up checks, not get mistaken for a complete deployment.

$ docker container ls --all --filter name='my-web' --filter name='my-worker' \
    --format 'table {{.Names}}\t{{.Status}}'

Filters and status output are useful evidence, but they do not test an HTTP endpoint or a queue consumer. For an application-level check, use the service's normal health probe, client request or monitoring check once Docker reports the containers as running.

6. Diagnose a failed or unhealthy restart

If Docker says the container does not exist, rerun docker container ls --all and check its exact name, ID and Docker context. If the command cannot connect to the daemon, fix that daemon or context issue before retrying; sudo is not a general repair. Use elevated privileges only when your Docker installation specifically requires them, and remember that membership of the Docker group grants host-level control.

If the container starts and immediately exits, inspect its logs and state without changing it:

$ docker container logs --tail 100 my-web
$ docker container inspect --format '{{.State.Status}} exit={{.State.ExitCode}} error={{.State.Error}}' my-web
running exit=0 error=

The example output is host-specific. An exit code other than 0, an error string or a repeated Restarting status points to the application, its configuration or its restart policy. Keep the original container until you have collected the evidence: recreating it can discard useful runtime details.

Done means

• The exact container name or ID was checked before the restart.
• The service interruption was scheduled and understood.
• The command returned status 0 and the intended container is running.
• A positive timeout was used when graceful shutdown needs more than the default.
• The stop signal was left at its configured value unless the application requires another.
• Logs, exit state and an application-level health check were reviewed when recovery mattered.