Docker

Docker List Containers Examples (docker ps)

1. Introduction

In this post we will explore the command docker ps which is used to list Docker containers. We will also explore the various options of this command.  This tutorial assumes that you have a working Docker installation.  If you are new to Docker please read how to install Docker and create containers before proceeding further.

2. Docker Container – It’s Properties and State Machine

A Docker container is simply an image with a read-write file-system layer attached to it.  The command docker inspect provides an exhaustive list of properties. A few key properties are listed below

CategoryDescriptionProperties
General container settingsGeneral properties that describe the Docker containerId, hostname, domain, user, environment, created date, Path, Args, State, Image name, Container name, Drivers, Local file-system paths, …
Host configurationHost configuration of the containercontainer ID file, log file, port bindings, restart policy, auto remove, volumes, cpu share details, memory, control-group details, block device details, disk quota, kernel memory, swap memory, …
Network settingsGives the network settings of the containerSandboxID, Ports, IP addresses, Gateway, MacAddress, Networks, …

 

 
A Docker container can be in one of the following states – created, restarting, running, paused, and exited.  The state machine for a container is shown below

docker list containers - State machine of a docker container
State machine of a Docker container

A Docker container starts its life in the state created.  A new container can be created by using the docker create command. From this state a container goes into the state running. This happens due to the docker start or docker run command. From here a container can be temporarily paused through the docker pause command. If the restart flag is set to true then the container can go into restarting state by itself. It can also be manually taken into this state by the docker restart command. Finally, a container can go into the state exited through the docker stop command or when it is automatically stopped. A container can be automatically stopped due to an error or because the container is done with it’s designated task.

Let us now take a look at some ways to list Docker containers.

3. The docker ps Command – Docker List Containers

docker ps is the essential command to list existing docker containers. Let us explore the different options of this command.

3.1 List All Running Containers

The default invocation of the docker ps command without any options lists out all containers in running state

$ docker ps

docker list containers - Output of docker ps
Output of docker ps

I have only one running container at present. So docker ps showed only one entry. If there were no running containers or if it is a fresh Docker installation docker ps will not show any containers. Let us try that by stopping all running containers and try docker ps again like below.

Output of docker ps when there are no running containers
Output of docker ps when there are no running containers

3.2 List All Containers Ever Created

The --all or -a option must be used to list all containers. Like so

$ docker ps --all

Output of docker ps --all
Output of docker ps –all

3.3 List Only Container IDs – Quiet Output

The --quiet or -q option will display only the container ids. By default this option will show the container IDs of the containers in running state. If you need container IDs for all containers then this should be combined with the option --all or -a

Docker List Containers - Output of docker ps --quiet for all containers
Output of docker ps –quiet for all containers

This option comes in handy while writing shell scripts or to pipe the output of this command to another command. For instance, the output of this command can be fed into the docker command to remove all stopped containers from your docker installation like this

$ docker rm `docker ps --all`

To remove all containers in any state you can tweak this further like below.

$ docker rm --force `docker ps --all`

3.4 Show Details of Last x Created Containers

The --last x or -n x option can be used to list the last x created containers where x should be replaced with an integer. If x is a very large number then all existing containers will be listed. Otherwise, only the last x containers will be listed. For instance too see the last 3 created containers the command would be

$ docker ps --last 3

This can also be combined with the option --quiet to list only the container IDs like so

$ docker ps --last 3 --quiet

docker list containers - Various outputs of docker ps --last
Various outputs of docker ps –last

3.5 Show Details of the Latest Created Container

The option --latest or -l to see only the latest created container. This is called like below

$ docker ps --latest

This is also equivalent to calling docker ps with the option --last 1

$ docker ps --last 1

Outputs of docker ps --latest
Outputs of docker ps –latest

3.6 Format output of docker ps

The default output of docker ps can be changed using the --format option. For example the command docker ps --all --format {{.ID}} will list out only the IDs of all containers

$ docker ps --all --format {{.ID}}

Output of docker ps formatted only by ID
Output of docker ps formatted only by ID

Do note that the above output is the same as the output of docker ps --all --quiet. okay, lets see another example – list all container IDs and their images as a table. The command to do this is docker ps --all --format "table {{.ID}}\t{{.Image}}". In the format string the placeholders .ID and .Image print the container ID and image name respectively. The table keyword helps to format the output as a table. The \t inserts a tab between the columns to align them tidily

$ docker ps --all --format "table {{.ID}}\t{{.Image}}"

Output of docker ps formatted by container ID and image
Output of docker ps formatted by container ID and image

3.6.1 List of all sub-options for docker ps –format

The complete list of sub-options for --format option are these:

PlaceholderMeaning
.CommandPrint command used to start the container
.CreatedAtPrint the time when the container was created
.IDPrint Container ID
.ImagePrint Image ID
.LabelPrint value of a specific label assigned to this container
.LabelsPrint all labels assigned to container
.MountsPrint names of all volumes mounted within this container
.NamesPrint container names
.PortsPrint all exposed ports
.RunningForPrint the time elapsed since the container was started
.SizePrint container disk size
.StatusPrint current container status

We will close this section with one more example – List out container ID, name, created at, current status, running time and all mount points

$ docker ps --all --format "table {{.ID}}\t{{.Names}}\t{{.CreatedAt}}\t{{.Status}}\t{{.RunningFor}}"

Output of docker ps with many format options
Output of docker ps with many format options

3.7 Filter Output of docker ps

The --filter or -f option provides a set of options to filter the output of docker ps. The below sections provide more details about the options. For the below example we assume the starting status to be as below

$ docker ps --all --format "table {{.ID}}\t{{.Names}}\t{{.CreatedAt}}\t{{.Status}}\t{{.RunningFor}}"

Initial output of docker ps before starting --filter option
Initial output of docker ps before starting –filter option

Let us start with an example. The --filter=status= is used to show only containers with a specific status. The can be one of created, restarted, running, paused, exited, or dead.
The command to filter output to show only running containers, for example, would be this

$ docker ps --all --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" --filter=status=running

Filter docker ps output by running containers
Filter docker ps output by running containers

The –format option in the above command can also be ignored. It has been used for brevity of the output of docker ps. You can also chain different filter options. For example the command to show both running and exited containers would be given as below

$ docker ps --all --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" --filter=status=running --filter=status=exited

Filter output of docker ps by running and exited containers
Filter output of docker ps by running and exited containers

Here is another example. To see a list of all containers created from a particular image we can use the ancestor filter option as below

$ docker ps --all --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" --filter=ancestor=alpine:latest

Output of docker ps filtered by ancestors of one image
Output of docker ps filtered by ancestors of one image

3.7.1 List of all sub-options for docker ps –filter

The full list of options for --filter is in this below table:

Filter optionDescriptionUsage example(s)
ancestorFilters output by containers created from an image or it’s descendant–filter=ancestor=alpine:latest
–filter=ancestor=openjdk:8u111
–filter=ancestor=my-own-image
beforeFilters output by containers created before a specific container id or container name–filter=before=1a369514e129
–filter=before=stupefied_lalande
exitedFilters output by specific exit code–filter=exited=0
–filter=exited=0 –filter=exited=1
idFilters output by specific container id–filter=id=1a369514e129
labelFilters output by specific labels–filter=label=
–filter=label==
nameFilters output by a container name–filter=name=stupefied_lalande
networkFilters output by a containers connected to specific network(s)–filter=network=
–filter=network=
sinceFilters output by containers created after a specific container id or container name–filter=since=1a369514e129
–filter=since=stupefied_lalande
statusFilters output by container status–filter=status=created
–filter=status=running
–filter=status=paused
–filter=status=restarting
–filter=status=exited
–filter=status=dead
volumeFilters output by containers bound to specific volume(s) or mount-point(s)–filter=volume=
–filter=volume=

3.8 Display Total File Sizes

The --size or -s option of docker ps is used to show the total file sizes occupied by a docker container. By default this option will show the sizes of all running containers. To get the file sizes of all containers couple --size with --all option like so

show file sizes of all containers
show file sizes of all containers

4. Summary

We saw the various ways to use the docker ps command to list Docker containers.  The state machine of Docker containers was also discussed. The docker ps command provides various options to look into the details of the containers and to filter and format the output as we need. All the options were discussed and where feasible some sub-options were also discussed. The Docker manual entry for docker ps contains more details and examples for your reference.

Last updated on Feb. 27th, 2022

Hariharan Narayanan

Hari graduated from the School of Computer and Information Sciences in the University of Hyderabad. Over his career he has been involved in many complex projects in mobile applications, enterprise applications, distributed applications, micro-services, and other platforms and frameworks. He works as a consultant and is mainly involved with projects based on Java, C++ and Big Data technologies.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Inline Feedbacks
View all comments
Back to top button