Restart a Docker Container Without Losing Its Configuration

You will finish with a controlled way to restart one or more Docker containers, select a stop signal and timeout when needed, and verify that the containers came back. A restart changes the running process and can briefly interrupt service, but it does not recreate the container or change its image, mounts, environment or restart policy.

Allow about ten minutes. You need Docker CLI 29.8.1 or a compatible Docker CLI, access to the Docker daemon, and the exact name or ID of the target container. The examples use example-web, which is a placeholder. Do not paste it unchanged unless a container with that name is genuinely the one you intend to restart.

1. Check the installed command

Read the local command contract before choosing an option. This is an ordinary, read-only check:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker restart --help
Usage:  docker restart [OPTIONS] CONTAINER [CONTAINER...]

Restart one or more containers

Options:
  -s, --signal string   Signal to send to the container
  -t, --timeout int     Seconds to wait before killing the container

The installed package is docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble. The command is an alias for docker container restart, so either spelling is valid. The rest of this guide uses the shorter form.

2. Identify the target without changing it

List all containers, including stopped ones. This does not restart or alter anything:

$ docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
CONTAINER ID   NAMES          STATUS
abc123def456   example-web    Up 2 hours
def456abc123   example-worker Exited (1) 10 minutes ago

Use the exact value in the NAMES column, or a container ID or unambiguous ID prefix. Check the status again if another operator or an automated restart policy may have changed it:

$ docker inspect --format 'name={{.Name}} status={{.State.Status}} restart-count={{.RestartCount}}' example-web
name=/example-web status=running restart-count=0

If the inspect command says that the container does not exist, stop here and correct the name or Docker context. Do not guess between similarly named Compose projects.

3. Restart one container with its normal stop behaviour

After confirming the target, issue the restart. This uses the image's configured stop signal when one exists, or Docker's normal default, and waits according to the container's configured stop timeout:

$ docker restart example-web
example-web

A successful command prints the container name and exits with status 0. Capture that status when using the command in a script:

$ docker restart example-web
example-web
$ printf 'restart command status: %s\n' "$?"
restart command status: 0

The command stops the container and starts that same container again. It does not pull a newer image, apply changed environment variables, rebuild an image or recreate a Compose service. Those are separate operations. A restart also disconnects attached clients, so do not treat it as an invisible health check.

4. Verify that the container is running again

Check the state rather than relying only on the CLI's acknowledgement:

$ docker ps --filter 'name=^/example-web$' --format 'name={{.Names}} status={{.Status}}'
name=example-web status=Up 3 seconds

For a container with a health check, include its health state:

$ docker inspect --format 'status={{.State.Status}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}not-configured{{end}}' example-web
status=running health=healthy

These values are examples. A running container can still have a broken application, and a health check may take time to move from starting to healthy. If the state is restarting or exited, inspect the recent logs and exit details before repeating the restart:

$ docker logs --tail 100 example-web
$ docker inspect --format 'status={{.State.Status}} exit={{.State.ExitCode}} error={{.State.Error}}' example-web

5. Restart several containers deliberately

You can pass more than one target, but Docker will interrupt each named workload. Review the full list before pressing Enter:

$ docker restart example-web example-worker
example-web
example-worker

There is no transaction that rolls all targets back if one restart fails. Verify each container afterwards:

$ docker ps -a --filter 'name=^/example-' --format 'table {{.Names}}\t{{.Status}}'
NAMES          STATUS
example-web    Up 12 seconds
example-worker Up 11 seconds

A broad shell expansion such as docker restart $(docker ps -aq) is a distraction trap and a dangerous production habit. It targets every container, including unrelated stopped containers. Build a short, reviewed list instead.

6. Choose a signal and timeout for a slow shutdown

The --signal option selects the signal sent when stopping the container. The image's STOPSIGNAL or the container's configured stop signal normally supplies this value. Use an explicit signal only when the application documentation requires it:

$ docker restart --signal SIGTERM example-web
example-web

The --timeout option sets how many seconds Docker waits after sending that signal before using SIGKILL. For example, allow 30 seconds for a service that flushes work during a normal shutdown:

$ docker restart --timeout 30 example-web
example-web

On the installed CLI, -t defaults to 0 in the command help. Docker still applies the container or daemon stop-timeout behaviour when no explicit value is supplied. The official reference documents -1 as waiting indefinitely. Avoid an indefinite wait in an unattended script unless you also have an external timeout and an operator-approved recovery plan.

A short timeout can turn a graceful stop into a forced kill, which may lose in-memory work or leave application-level recovery to the next start. A long timeout can leave a failed deployment unavailable while Docker waits. Choose it from the service's shutdown behaviour, not by habit.

7. Recover from a failed or unwanted restart

If the command reports an error, do not immediately repeat it. Confirm the daemon and target context, then inspect the container:

$ docker context show
$ docker inspect --format 'name={{.Name}} status={{.State.Status}} error={{.State.Error}}' example-web
$ docker logs --tail 100 example-web

If the container is stopped and you only need to start it, use docker start example-web. That avoids asking Docker to stop an already stopped container. If the application came back with a fault, the undo for this guide is not another restart: restore the service's previous operating state according to its deployment procedure, or stop it deliberately with docker stop example-web while investigating. Do not remove the container as a quick fix; removal is a separate, destructive action.

Docker access may require membership of the Docker socket's authorised group or elevated privileges. Prefer your normal authorised account. If it receives a daemon permission error, use the host's approved privilege path, such as sudo docker restart example-web, only when you are authorised. sudo does not make the container name correct and does not fix an application that fails during startup.