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
| Category | Description | Properties |
|---|---|---|
| General container settings | General properties that describe the Docker container | Id, hostname, domain, user, environment, created date, Path, Args, State, Image name, Container name, Drivers, Local file-system paths, … |
| Host configuration | Host configuration of the container | container 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 settings | Gives the network settings of the container | SandboxID, 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
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
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.
3.2 List All Containers Ever Created
The --all or -a option must be used to list all containers. Like so
$ 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
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
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
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}}
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}}"
3.6.1 List of all sub-options for docker ps –format
The complete list of sub-options for --format option are these:
| Placeholder | Meaning |
|---|---|
| .Command | Print command used to start the container |
| .CreatedAt | Print the time when the container was created |
| .ID | Print Container ID |
| .Image | Print Image ID |
| .Label | Print value of a specific label assigned to this container |
| .Labels | Print all labels assigned to container |
| .Mounts | Print names of all volumes mounted within this container |
| .Names | Print container names |
| .Ports | Print all exposed ports |
| .RunningFor | Print the time elapsed since the container was started |
| .Size | Print container disk size |
| .Status | Print 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}}"
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}}"
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
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
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
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 option | Description | Usage example(s) |
|---|---|---|
| ancestor | Filters output by containers created from an image or it’s descendant | –filter=ancestor=alpine:latest –filter=ancestor=openjdk:8u111 –filter=ancestor=my-own-image |
| before | Filters output by containers created before a specific container id or container name | –filter=before=1a369514e129 –filter=before=stupefied_lalande |
| exited | Filters output by specific exit code | –filter=exited=0 –filter=exited=0 –filter=exited=1 |
| id | Filters output by specific container id | –filter=id=1a369514e129 |
| label | Filters output by specific labels | –filter=label= –filter=label== |
| name | Filters output by a container name | –filter=name=stupefied_lalande |
| network | Filters output by a containers connected to specific network(s) | –filter=network= –filter=network= |
| since | Filters output by containers created after a specific container id or container name | –filter=since=1a369514e129 –filter=since=stupefied_lalande |
| status | Filters output by container status | –filter=status=created –filter=status=running –filter=status=paused –filter=status=restarting –filter=status=exited –filter=status=dead |
| volume | Filters 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
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
