Docker services

Services in Docker swarm

Don't use the constructor directly. Instead use

from python_on_whales import docker

my_docker_service = docker.service.inspect("my-service")

my_docker_service = docker.service.create("busybox", ["ping", "www.google.com"])

For type hints, use this

from python_on_whales import Service

def print_creation_time(some_service: Service):
    print(some_service.created_at)

Attributes

It attributes are the same that you get with the command line: docker service inspect ...

To get a complete description of those attributes, you can take a look at the daemon api reference page and click on "200 No error".

An example is worth many lines of descriptions.

In [1]: from python_on_whales import docker

In [2]: docker.swarm.init()

In [3]: my_service = docker.service.create("busybox", ["ping", "www.google.com"])

In [4]: def super_print(obj):
   ...:     print(f"type = {type(obj)}, value = {obj}")
   ...:

In [4]: super_print(service.id)
type = <class 'str'>, value = j2a08lebrqd3s4rpifdiv53aj

In [5]: super_print(service.version)
type = <class 'python_on_whales.components.service.models.ServiceVersion'>, value = index=11

In [6]: super_print(service.created_at)
type = <class 'datetime.datetime'>, value = 2025-10-24 09:07:42.790289+00:00

In [7]: super_print(service.updated_at)
type = <class 'datetime.datetime'>, value = 2025-10-24 09:07:42.790289+00:00

In [8]: super_print(service.spec.name)
type = <class 'str'>, value = competent_ramanujan

In [9]: super_print(service.spec.labels)
type = <class 'dict'>, value = {}

In [10]: super_print(service.spec.mode)
type = <class 'dict'>, value = {'Replicated': {'Replicas': 1}}

In [11]: super_print(service.spec.update_config)
type = <class 'python_on_whales.components.service.models.ChangeConfig'>, value = parallelism=1 failure_action='pause' monitor=5000000000 max_failure_ratio=0.0 order='stop-first'

In [12]: super_print(service.spec.rollback_config)
type = <class 'python_on_whales.components.service.models.ChangeConfig'>, value = parallelism=1 failure_action='pause' monitor=5000000000 max_failure_ratio=0.0 order='stop-first'

In [13]: super_print(service.spec.task_template.container_spec.image)
type = <class 'str'>, value = busybox:latest@sha256:2f590fc602ce325cbff2ccfc39499014d039546dc400ef8bbf5c6ffb860632e7

In [14]: super_print(service.spec.task_template.container_spec.labels)
type = <class 'NoneType'>, value = None

In [15]: super_print(service.spec.task_template.container_spec.privileges)
type = <class 'NoneType'>, value = None

In [16]: super_print(service.spec.task_template.container_spec.stop_grace_period)
type = <class 'int'>, value = 10000000000

In [17]: super_print(service.spec.task_template.container_spec.isolation)
type = <class 'str'>, value = default

In [18]: super_print(service.spec.task_template.container_spec.env)
type = <class 'NoneType'>, value = None

In [19]: super_print(service.spec.task_template.resources.limits)
type = <class 'python_on_whales.components.service.models.CPUMemoryQuotas'>, value = nano_cpus=None memory_bytes=None

In [20]: super_print(service.spec.task_template.resources.reservations)
type = <class 'python_on_whales.components.service.models.CPUMemoryQuotas'>, value = nano_cpus=None memory_bytes=None

In [21]: super_print(service.previous_spec)
type = <class 'NoneType'>, value = None

In [22]: super_print(service.endpoint.spec)
type = <class 'python_on_whales.components.service.models.ServiceEndpointSpec'>, value = mode=None ports=None

In [23]: super_print(service.endpoint.ports)
type = <class 'NoneType'>, value = None

In [24]: super_print(service.endpoint.virtual_ips)
type = <class 'NoneType'>, value = None

In [25]: super_print(service.update_status)
type = <class 'NoneType'>, value = None

Methods

Service

exists

exists()

Returns True if the service is still present in the swarm, False if the service has been removed.

ps

ps()

Returns the list of tasks of this service.

remove

remove()

Removes this service

It's also possible to use a service as a context manager. By using a context manager, you ensures that the service will be removed even if an exception occurs.

from python_on_whales import docker

docker.swarm.init()
with docker.service.create("ubuntu", ["sleep", "infinity"]) as my_service:
    print("I'm doing things with the service here")
    print(my_service.update_status)

print("I'm out of the context manager, the service has been removed.")

scale

scale(new_scale, detach=False)

Change the scale of a service.

See the docker.service.scale command for information about the arguments.

update

update(detach=False, force=False, image=None, with_registry_authentication=False, quiet=False, replicas=None)

Updates a service

See the docker.service.update command for information about the arguments.