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.
  • isolation (string) – Isolation technology used by the service’s containers. Only used for Windows containers.
  • 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.
  • tty (boolean) – Whether a pseudo-TTY should be allocated.
  • groups (list) – A list of additional groups that the container process will run as.
  • open_stdin (boolean) – Open stdin
  • read_only (boolean) – Mount the container’s root filesystem as read only.
  • stop_signal (string) – Set signal to stop the service’s containers
  • healthcheck (Healthcheck) – Healthcheck configuration for this service.
  • hosts (dict) – A set of host to IP mappings to add to the container’s hosts file.
  • dns_config (DNSConfig) – Specification for DNS related configurations in resolver configuration file.
  • configs (list) – List of ConfigReference that will be exposed to the service.
  • privileges (Privileges) – Security options for the service’s containers.

(Service) The created service.


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

get(service_id, insert_defaults=None)

Get a service.

  • service_id (str) – The ID of the service.
  • insert_defaults (boolean) – If true, default values will be merged into the output.

The service.

Return type:


  • docker.errors.NotFound – If the service does not exist.
  • docker.errors.APIError – If the server returns an error.
  • docker.errors.InvalidVersion – If one of the arguments is not supported with the current API version.

List services.

Parameters:filters (dict) – Filters to process on the nodes list. Valid filters: id, name , label and mode. 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.