Introduction

To disable auto-restart on a Docker container, run docker update --restart no <container>. This works on running containers without requiring a stop-and-recreate cycle. If you are creating a new container, pass --restart no to docker run, though this is already the default behavior when no restart policy is specified.

Docker Restart Policies Explained

Docker supports four restart policies that control what happens when a container exits. These policies are set with the --restart flag during docker run or changed later with docker update.

1# No automatic restart (default)
2docker run --restart no nginx
3
4# Always restart, regardless of exit code
5docker run --restart always nginx
6
7# Always restart, except when manually stopped
8docker run --restart unless-stopped nginx
9
10# Restart only on non-zero exit code, with optional retry limit
11docker run --restart on-failure:5 nginx

The key distinction between always and unless-stopped is behavior after a Docker daemon restart (such as a system reboot). A container with always restarts even if you ran docker stop before the reboot. A container with unless-stopped stays stopped if it was manually stopped before the daemon went down.

Disable Auto-Restart on a Running Container

The docker update command changes a container's configuration without requiring you to stop, remove, and recreate it. This has been available since Docker 1.11.

docker update --restart no my-container

You can verify the change took effect:

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' my-container

Expected output:

no

This command works on both running and stopped containers.

Disable Auto-Restart on Multiple Containers at Once

If several containers have restart policies you want to clear, pass multiple names or IDs:

docker update --restart no container1 container2 container3

To disable auto-restart on every running container in one command:

docker update --restart no $(docker ps -q)

To target all containers, including stopped ones:

docker update --restart no $(docker ps -aq)

Disable Auto-Restart When Creating a New Container

When you run docker run without specifying --restart, the default policy is no. Explicitly stating it is unnecessary but sometimes useful for clarity in scripts and documentation:

docker run --restart no -d -p 8080:80 nginx

Disable Auto-Restart in Docker Compose

In Docker Compose files, the restart policy is set with the restart key. To disable it, either omit the key entirely (the default is no) or set it explicitly:

1services:
2  web:
3    image: nginx
4    restart: "no"
5    ports:
6      - "8080:80"

Note that no must be quoted in YAML because unquoted no is interpreted as a boolean false. This is a common source of parse errors.

To change the restart policy on a running Compose service without recreating it:

docker update --restart no $(docker compose ps -q web)

If you prefer to recreate the service with the updated configuration:

# After changing restart: "no" in docker-compose.yml
docker compose up -d web

Checking Current Restart Policy

Before changing a policy, you may want to inspect what is currently set:

1# Single container
2docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' my-container
3
4# All containers with their restart policies
5docker ps -a --format 'table {{.Names}}\t{{.Status}}' | head -5
6docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

For a cleaner overview:

docker inspect --format '{{.Name}}: restart={{.HostConfig.RestartPolicy.Name}}, max_retries={{.HostConfig.RestartPolicy.MaximumRetryCount}}' $(docker ps -aq)

Understanding on-failure with Retry Limits

The on-failure policy accepts an optional maximum retry count. When the retry limit is reached, the container stops restarting. This is a good middle ground between always (which can create restart loops) and no (which offers no resilience).

1# Restart up to 3 times on failure
2docker run --restart on-failure:3 -d my-app
3
4# Check how many restarts have occurred
5docker inspect --format '{{.RestartCount}}' my-app

If a container with on-failure:3 keeps crashing and hits the limit, you need to fix the underlying issue and then manually restart it. The counter resets if you docker stop and docker start the container.

Restart Policies in Orchestration Environments

Docker restart policies apply to standalone Docker containers. In orchestration platforms, container lifecycle is managed differently:

Docker Swarm uses service-level restart policies defined in the deploy section of a Compose file. The docker update --restart command does not apply to Swarm services. Instead, update the service:

docker service update --restart-condition none my-service

Kubernetes manages restarts through the Pod restartPolicy field, which accepts Always, OnFailure, or Never. Docker-level restart policies are ignored entirely when containers run inside Kubernetes pods.

The takeaway is that docker update --restart no is the correct approach only for standalone Docker containers, not for orchestrated deployments.

Common Pitfalls

Thinking you need to recreate the container. Before Docker 1.11, changing the restart policy required stopping, removing, and recreating the container. With docker update, this is no longer necessary. Many older tutorials still recommend the stop-remove-recreate workflow.

Forgetting to quote "no" in YAML. In Docker Compose files, restart: no (unquoted) is parsed as restart: false, which is not a valid restart policy and can cause unexpected behavior. Always use restart: "no".

Confusing always and unless-stopped during reboots. Developers often set always thinking it means "keep running until I stop it." But always also restarts the container after a system reboot even if it was manually stopped before the reboot. If that is not what you want, use unless-stopped.

Not checking the restart count on on-failure containers. A container configured with on-failure:5 that has restarted 5 times will silently stay dead. If you are troubleshooting why a container is not running, check docker inspect for the restart count and the exit code.

Applying Docker restart policies in Kubernetes. Docker-level restart flags are ignored by Kubernetes. The Pod spec's restartPolicy controls container restarts in that environment.

Summary

• Use docker update --restart no <container> to disable auto-restart on an existing container without recreating it.
• The default restart policy for docker run is already no, so new containers do not auto-restart unless explicitly configured.
• In Docker Compose, always quote the value: restart: "no".
• Use docker inspect to verify the current restart policy before and after changes.
• The always policy restarts containers even after system reboots. Use unless-stopped if you want manual stops to be respected across reboots.
• In orchestrated environments (Swarm, Kubernetes), container restart is managed at the service or pod level, not through Docker restart policies.