docker service update

Estimated reading time: 6 minutes


Update a service


docker service update [OPTIONS] SERVICE


Name, shorthand Default Description
--args   Service command args
--constraint-add   Add or update a placement constraint
--constraint-rm   Remove a constraint
--container-label-add   Add or update a container label
--container-label-rm   Remove a container label by its key
--dns-add   Add or update a custom DNS server
--dns-option-add   Add or update a DNS option
--dns-option-rm   Remove a DNS option
--dns-rm   Remove a custom DNS server
--dns-search-add   Add or update a custom DNS search domain
--dns-search-rm   Remove a DNS search domain
--endpoint-mode   Endpoint mode (vip or dnsrr)
--env-add   Add or update an environment variable
--env-rm   Remove an environment variable
--force false Force update even if no changes require it
--group-add   Add an additional supplementary user group to the container
--group-rm   Remove a previously added supplementary user group from the container
--health-cmd   Command to run to check health
--health-interval   Time between running the check (ns|us|ms|s|m|h)
--health-retries 0 Consecutive failures needed to report unhealthy
--health-timeout   Maximum time to allow one check to run (ns|us|ms|s|m|h)
--host-add   Add or update a custom host-to-IP mapping (host:ip)
--host-rm   Remove a custom host-to-IP mapping (host:ip)
--hostname   Container hostname
--image   Service image tag
--label-add   Add or update a service label
--label-rm   Remove a label by its key
--limit-cpu 0.000 Limit CPUs
--limit-memory 0 B Limit Memory
--log-driver   Logging driver for service
--log-opt   Logging driver options
--mount-add   Add or update a mount on a service
--mount-rm   Remove a mount by its target path
--no-healthcheck false Disable any container-specified HEALTHCHECK
--publish-add   Add or update a published port
--publish-rm   Remove a published port by its target port
--replicas   Number of tasks
--reserve-cpu 0.000 Reserve CPUs
--reserve-memory 0 B Reserve Memory
--restart-condition   Restart when condition is met (none, on-failure, or any)
--restart-delay   Delay between restart attempts (ns|us|ms|s|m|h)
--restart-max-attempts   Maximum number of restarts before giving up
--restart-window   Window used to evaluate the restart policy (ns|us|ms|s|m|h)
--rollback false Rollback to previous specification
--secret-add   Add or update a secret on a service
--secret-rm   Remove a secret
--stop-grace-period   Time to wait before force killing a container (ns|us|ms|s|m|h)
--tty, -t false Allocate a pseudo-TTY
--update-delay 0 Delay between updates (ns|us|ms|s|m|h) (default 0s)
--update-failure-action pause Action on update failure (pause|continue)
--update-max-failure-ratio 0 Failure rate to tolerate during an update
--update-monitor 0 Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s)
--update-parallelism 1 Maximum number of tasks updated simultaneously (0 to update all at once)
--user, -u   Username or UID (format: <name|uid>[:<group|gid>])
--with-registry-auth false Send registry authentication details to swarm agents
--workdir, -w   Working directory inside the container

Parent command

Command Description
docker service Manage services
Command Description
docker service create Create a new service
docker service inspect Display detailed information on one or more services
docker service logs Fetch the logs of a service
docker service ls List services
docker service ps List the tasks of one or more services
docker service rm Remove one or more services
docker service scale Scale one or multiple replicated services
docker service update Update a service


Update a service

$ docker service update --limit-cpu 2 redis

Perform a rolling restart with no parameter changes

$ docker service update --force --update-parallelism 1 --update-delay 30s redis

In this example, the --force flag causes the service’s tasks to be shut down and replaced with new ones even though none of the other parameters would normally cause that to happen. The --update-parallelism 1 setting ensures that only one task is replaced at a time (this is the default behavior). The --update-delay 30s setting introduces a 30 second delay between tasks, so that the rolling restart happens gradually.

Adding and removing mounts

Use the --mount-add or --mount-rm options add or remove a service’s bind-mounts or volumes.

The following example creates a service which mounts the test-data volume to /somewhere. The next step updates the service to also mount the other-volume volume to /somewhere-elsevolume, The last step unmounts the /somewhere mount point, effectively removing the test-data volume. Each command returns the service name.

  • The --mount-add flag takes the same parameters as the --mount flag on service create. Refer to the volumes and bind-mounts section in the service create reference for details.

  • The --mount-rm flag takes the target path of the mount.

$ docker service create \
    --name=myservice \
    --mount \
      type=volume,source=test-data,target=/somewhere \
    nginx:alpine \


$ docker service update \
    --mount-add \
      type=volume,source=other-volume,target=/somewhere-else \


$ docker service update --mount-rm /somewhere myservice


Adding and removing secrets

Use the --secret-add or --secret-rm options add or remove a service’s secrets.

The following example adds a secret named ssh-2 and removes ssh-1:

$ docker service update \
    --secret-add source=ssh-2,target=ssh-2 \
    --secret-rm ssh-1 \

Update services using templates

Some flags of service update support the use of templating. See service create for the reference.

chat icon Feedback? Suggestions? Can't find something in the docs?
Edit this page Request docs changes Get support
Rate this page: