List Docker Swarm Services Without Losing the Useful Detail

You will finish with a repeatable way to inspect the services known to a Docker Swarm manager, narrow the list, and format the result for a script or a human. The examples use Docker CLI 29.8.1 from the installed docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need the Docker CLI and access to a Swarm manager. This command only lists services, so the guide does not create, update or remove any service. Do not use sudo merely to make a listing work: a worker node or an unavailable daemon is a topology or connectivity problem, not normally a file-permission problem.

1. Confirm the installed command

Start with the local help output. This is an ordinary, read-only command and does not contact the Swarm manager:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker service ls --help
Usage:  docker service ls [OPTIONS]

List services

The command has the alias docker service list, but use ls in scripts when you want to match the installed manual and examples. The command's default output is a table with headers. The available options are --filter, --format and --quiet.

2. List every service from a manager

Run the plain listing from a Swarm manager:

$ docker service ls
ID             NAME        MODE         REPLICAS  IMAGE
abc123def456   web         replicated   3/3       nginx:alpine
fed654cba321   log-agent   global       3/3       fluent/fluent-bit:latest

The exact IDs, names, images and counts are host-specific. In the table, REPLICAS shows actual tasks followed by the desired task count. A value such as 2/3 is a useful warning that the service is not currently meeting its desired state, but it does not explain why. Use docker service ps SERVICE_NAME as a separate investigation when you need task placement and error details.

This is a Swarm cluster-management command. Docker's client documentation says it must be run on a manager node. A worker cannot answer the service-list request just because it can run ordinary local containers.

If the command reports that the node is not a Swarm manager, move the command to a manager or use the Docker context that points there. If it reports that the daemon cannot be reached, check the selected context and daemon connectivity first:

$ docker context show
$ docker info
$ docker service ls

docker info is read-only, but it may expose environment details in its output. Do not paste credentials, registry tokens or private hostnames into a public ticket.

3. Narrow the list with a supported filter

Filters use the form key=value. The supported service-list keys are id, label, mode and name. Quote the complete filter so shell metacharacters or whitespace cannot alter it.

To find services whose names start with web:

$ docker service ls --filter 'name=web'
ID             NAME       MODE         REPLICAS  IMAGE
abc123def456   web        replicated   3/3       nginx:alpine
789abc012def   web-cache  replicated   3/3       redis:7.4-alpine

The name filter matches a name or its prefix. The ID filter works similarly for an ID or ID prefix:

$ docker service ls --filter 'id=abc123'
ID             NAME  MODE        REPLICAS  IMAGE
abc123def456   web   replicated  3/3       nginx:alpine

For deployment checks, filter by mode:

$ docker service ls --filter 'mode=global'

A label filter can match the presence of a label, or a particular value:

$ docker service ls --filter 'label=team'
$ docker service ls --filter 'label=team=platform'

Do not assume that an unsupported filter silently does what you intended. Keep filters to the four documented keys, and use multiple --filter flags only when you have checked how your installed Docker version combines them.

4. Produce a stable machine-readable view

Use --format when a human-oriented table is inconvenient. The installed manual supports a Go template, a table template, and the json directive. The documented service fields are .ID, .Name, .Mode, .Replicas, .Image and .Ports.

For a compact report with no headers:

$ docker service ls --format '{{.Name}}: {{.Mode}} {{.Replicas}}'
web: replicated 3/3
log-agent: global 3/3

Use the table directive when you want headers while choosing the columns:

$ docker service ls --format 'table {{.Name}}\t{{.Mode}}\t{{.Replicas}}'
NAME        MODE        REPLICAS
web         replicated  3/3
log-agent   global      3/3

For one JSON object per service, use:

$ docker service ls --format json
{"ID":"abc123def456","Image":"nginx:alpine","Mode":"replicated","Name":"web","Ports":"","Replicas":"3/3"}

These examples show representative values, not promises about your cluster. Treat the output as records only after checking the command's exit status. A script should fail clearly when Docker cannot contact a manager, rather than interpreting an empty variable as an empty cluster.

5. Use quiet mode only for IDs

--quiet or -q prints only service IDs:

$ docker service ls --quiet
abc123def456
fed654cba321

This is useful when another command accepts service IDs, but it deliberately removes names and status fields. If you need to identify a service in an alert or log, prefer a template containing both .ID and .Name.

Do not pipe an unreviewed ID list straight into a command that changes services. Listing is non-destructive, but commands such as scaling, updating and removing services change cluster state and need a separate review, maintenance window and recovery plan.

6. Recover from misleading results

An empty result can mean that no services match the filter, not that the Swarm has no services. Rerun the plain command, then add the filter back:

$ docker service ls
$ docker service ls --filter 'name=THE_PREFIX_YOU_EXPECT'
$ docker service ls --filter 'label=THE_LABEL_YOU_EXPECT'

If the plain command fails, do not keep changing filters. Confirm the context with docker context show, check docker info, and verify that the selected endpoint is a manager. If the listing shows a partial replica count, use the service name with docker service ps and inspect the task error before changing the service.

There is no undo operation for docker service ls, because it does not alter the cluster. The safe recovery path is therefore diagnostic: restore the intended context, repeat the unfiltered listing, and compare the result with the expected manager.