Updated April 3, 2023
Introduction to Docker ps
The ‘docker ps’ is a Docker command to list the running containers by default; however, we can use different flags to get the list of other containers that are in stopped or exited status. We can also manipulate the output as per our requirement using flags. Docker has used the naming convention of ps from Linux; ps means ‘process status’ in Linux, and containers are actually running as a process on the Linux server; that’s why ‘docker ps’ is used to list the containers.
Syntax
docker ps [OPTIONS]
Options:
- -a, –all: It is used to show all containers
- -f, –filter: It is used to filter the list as per the condition applied
- –format: It is used to manipulate the output using a GO template that means how the output should look like
- -n, –last: It shows last created containers including all states
- -l, –latest: It is used to show the latest created container regardless of the state
- –no-trunc: It shows output without truncating the data
- -q, –quiet: It only displays the numeric ID of the containers
- -s, –size: It shows the total file size of the container
Command:
docker ps --help
How does the ps command work in Docker?
We need Docker CLI to be installed on the system from where we want to execute the ‘docker ps’ command. When we run the ‘docker ps’ command on the Docker CLI, Docker CLI parses the command in JSON and makes an API call to the Docker daemon, and Docker daemon sends back the list of the running containers if none of the options is mentioned in the command to the standard output, i.e. terminal.
Examples of Docker ps
We are going to learn different options used in the ‘docker ps’ command by taking scenarios, but before that, let’s create few containers using the below commands that we will use to perform and test the ‘docker ps’ command options:
docker run -d ubuntu sleep 3600
docker run -d alpine
docker run -d redis --label type=db
docker run -d --name test-con1 alpine
Example #1
List the running containers only.
Solution: We can use the ‘docker ps’ command simply to get the list of the running containers as it shows only the running containers by default.
docker ps
Explanation: As per the above snapshot, we can see that only one container is running right now.
Example #2
List all containers whether it is running or not.
Solution: We have to use the ‘-a’ or ‘–all’ option with the ‘docker ps’ command as below: –
docker ps -a
docker ps –all
Explanation: In the above snapshot, we can see that there are 5 containers because if you see the first snapshot where containers were created, I have run the same command twice.
Example #3
Use the ‘-f’ or ‘–filter’ option to filter out the specific container.
- Let’s filter out the container based on its container ID as below: –
docker ps -a -f "id=355b1893e282"
docker ps -a -f "id=35"
Note: – In the above snapshot, we have used the ‘-a’ flag as well to list the container even if it is not running. It is recommended to use the ‘-a’ flag with a filter. We can also use the short ID, but it must be unique.
- We can also filter the containers based on their name as below: –
docker container ls -a -f "name=test-con1"
docker container ls -a -f "name=test"
Note: – we can use a few keywords of the container name, and it will output the containers if the Docker daemon finds any container having those keywords in the name.
docker container ls -a -f "name=t"
docker container ls -a -f "name=con"
- We can use labels to filter the containers if containers have labels on them, so let’s create two more containers having labels on them.
docker run -d --label type=web nginx
docker run -d --label env=prod ubuntu sleep 3600
docker ps -f "label=env"
docker ps -f “label=type”
docker ps -f “label=type=web”
Explanation: In the above snapshot, we can see that we can list the containers which have a specific label; for ex., the first and the second commands show all the containers which have label “env” and “type” respectively on it regardless of the value and the third command shows all the container which has label “type” and the value of the label “type” must be “web”.
- We can also filter the containers based on their image name, image ID, tags, and layers.
docker ps -a -f ancestor=alpine
docker ps -a -f ancestor=3fd9065eaf02
Example #4
Format the output of the ‘docker ps’ command using the GO template with the format option.
- Let’s display only the container ID as below: –
docker ps --format {{.ID}}
docker ps -a --format {{.ID}}
- We can output more than one field; just we need to add that field as below: –
docker ps -a --format "{{.ID}} {{.Names}}"
- We can use the ‘\t’ to make some space and also provide any symbol in between to make the output pretty as below: –
docker ps -a --format "{{.ID}} -> \t {{.Names}}”
- We can output the fields that are not visible by default as well and use the ‘table’ directives to show the headers in the output as shown below: –
docker ps -a --format "table {{.ID}} \t {{.Names}} \t {{.Labels}} \t {{.Size}}"
In the above snapshot, we can now see the field headers as well.
Example #5
If we have a situation where we want to display the last n number of containers that are created, we can use the ‘-n’ option as below: –
docker ps -n 2
Note: – It includes stopped containers as well, so there is no need to specify the ‘-a’ flag.
Example #6
List the latest created container.
Solution: We can use the ‘-l’ option to list the lastest created container as below: –
docker ps -l
Example #7
Sometimes data of few columns get truncated because of screen size. List the containers without truncating the columns’ data.
Solution: We can use the ‘–no-trunc’ option to show all columns’ data as below: –
docker ps -n 2 --no-trunc
Note:- We can use this option with other options as well, like format, filter, etc.
Example #8
Show only the container ID of the containers.
Solution: We can use the ‘–quiet’ or ‘-q’ option to list only container ID as below: –
docker ps --quiet
docker ps -a --quiet
Example #9
Show the size of the container without using the ‘format’ option.
Solution: We have separate options ‘–size’ or ‘-s’ to list the size of the container.
docker ps -a -s
Advantages
- This command is very useful while doing troubleshooting, mostly useful with the ‘filter’ option.
- It helps to output the list of containers as per our need using the ‘format’ option that we can use for reporting purposes.
- It has multiple options that can be used together to filter and format the list of containers.
Rules and regulations for using a ps?
- The filter option only shows the running container if we filter based on labels, even if we use the ‘-a’ option.
- The output of ‘-n’ and ‘-l’ options show the container whether it is running or not, so no need to specify the ‘-a’ flag with these.
- We can use the ‘–no-trunc’ option with almost all the other options available in this command.
Conclusion – Docker ps
The ‘docker ps’ command is easy to use as compared to the ‘docker container ls’ as both commands have the same options and give us the same output, but ‘docker container ls’ is lengthy, so I prefer the ‘docker ps’ command over the ‘docker container ls’.
Recommended Articles
This is a guide to Docker ps. Here we discuss How the ps command works in Docker and Examples, along with the solution and explanation. You may also have a look at the following articles to learn more –
