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 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

Thank you!

Thank you!

Related Articles