Manage services on a swarm. For more information about services, see the Engine documentation.

Before you can use any of these methods, you first need to join or initialize a swarm.

Methods available on

class ServiceCollection
create(image, command=None, **kwargs)

Create a service. Similar to the docker service create command.

  • image (str) – The image name to use for the containers.
  • command (list of str or str) – Command to run.
  • args (list of str) – Arguments to the command.
  • constraints (list of str) – Placement constraints.
  • container_labels (dict) – Labels to apply to the container.
  • endpoint_spec (EndpointSpec) – Properties that can be configured to access and load balance a service. Default: None.
  • env (list of str) – Environment variables, in the form KEY=val.
  • hostname (string) – Hostname to set on the container.
  • labels (dict) – Labels to apply to the service.
  • log_driver (str) – Log driver to use for containers.
  • log_driver_options (dict) – Log driver options.
  • mode (ServiceMode) – Scheduling mode for the service. Default:None
  • mounts (list of str) – Mounts for the containers, in the form source:target:options, where options is either ro or rw.
  • name (str) – Name to give to the service.
  • networks (list of str) – List of network names or IDs to attach the service to. Default: None.
  • resources (Resources) – Resource limits and reservations.
  • restart_policy (RestartPolicy) – Restart policy for containers.
  • secrets (list of docker.types.SecretReference) – List of secrets accessible to containers for this service.
  • stop_grace_period (int) – Amount of time to wait for containers to terminate before forcefully killing them.
  • update_config (UpdateConfig) – Specification for the update strategy of the service. Default: None
  • user (str) – User to run commands as.
  • workdir (str) – Working directory for commands to run.

(Service) The created service.


docker.errors.APIError – If the server returns an error.


Get a service.


service_id (str) – The ID of the service.


The service.

Return type:


  • docker.errors.NotFound – If the service does not exist.
  • docker.errors.APIError – If the server returns an error.

List services.

Parameters:filters (dict) – Filters to process on the nodes list. Valid filters: id and name. Default: None.
Returns:The services.
Return type:(list of Service)
Raises:docker.errors.APIError – If the server returns an error.

Service objects

class Service

A service.


The ID of the object.


The ID of the object, truncated to 10 characters.


The service’s name.


The version number of the service. If this is not the same as the server, the update() function will not work and you will need to call reload() before calling it again.


The raw representation of this object from the server.


Load this object from the server again and update attrs with the new data.


Stop and remove the service.

Raises:docker.errors.APIError – If the server returns an error.

List the tasks in this service.

Parameters:filters (dict) – A map of filters to process on the tasks list. Valid filters: id, name, node, label, and desired-state.
Returns:List of task dictionaries.
Return type:(list)
Raises:docker.errors.APIError – If the server returns an error.

Update a service’s configuration. Similar to the docker service update command.

Takes the same parameters as create().

Raises:docker.errors.APIError – If the server returns an error.