Useful Examples of the Docker ps Command

Pratham Patel -

One of the first Docker commands you use is the docker ps command. It shows the running containers:

docker ps

Actually, running this command gives you a list of running containers and their unique container ID, image name, the command it is executing, time since it is running (uptime), and the ports it is using.

But you can do a bit more with it. You can display stopped containers, filter the result or just display the container IDs.

Let's take a bit more detailed look at this essential Docker command.

The docker ps command

Docker has an alias to show all running containers with a POSIX friendly naming convention.

That is the ps sub-command in Docker. It is an alias of docker container ls. Which, as you can guess, is used for listing docker containers.

Here is an example of executing docker ps on my computer:

$ docker ps 
CONTAINER ID   IMAGE                              COMMAND                  CREATED          STATUS                       PORTS                                   NAMES
58c7013a49c3   nextcloud                          "/entrypoint.sh apac…"   32 seconds ago   Up 31 seconds                0.0.0.0:8010->80/tcp, :::8010->80/tcp   nextcloud_server
140161b8b139   mariadb                            "docker-entrypoint.s…"   34 seconds ago   Up 32 seconds                3306/tcp                                nextcloud_db
73a6901a4846   lscr.io/linuxserver/transmission   "/init"                  17 minutes ago   Exited (137) 9 minutes ago                                           transmission_web

As you can see, this command displays details about all the running containers.

The details shown are the unique ID of the container, name of the image, command that the container is executing, date when the container was created, uptime, mapped ports and the container name.

As a sysadmin, you will often be using this command in a script. Docker provides a few options that can be helpful when you run docker ps in a script.

Show all the containers (not just the running ones)

As the UNIX ps command is used to show processes (programs that are being executed), Docker behaves similarly.

Running docker ps will only show the docker containers that are active.

If you stop a running container, it still exists, only that it is not running anymore.

To see the containers that are in the stopped state, use the --all (or -a) option like so:

docker ps --all

I stopped the container transmission_web. Let's see what I get in the output.

$ docker ps -a
CONTAINER ID   IMAGE                              COMMAND                  CREATED          STATUS                       PORTS                                   NAMES
58c7013a49c3   nextcloud                          "/entrypoint.sh apac…"   32 seconds ago   Up 31 seconds                0.0.0.0:8010->80/tcp, :::8010->80/tcp   nextcloud_server
140161b8b139   mariadb                            "docker-entrypoint.s…"   34 seconds ago   Up 32 seconds                3306/tcp                                nextcloud_db
73a6901a4846   lscr.io/linuxserver/transmission   "/init"                  17 minutes ago   Exited (137) 9 minutes ago                                           transmission_web

As you can see, the -a option also shows a container that was stopped.

Filter the output of docker ps for more accurate result

The docker ps command has a very useful option, --filter (or -f for short).

As evident from the option name, you can filter out the containers using the following fields:

  • id
  • name
  • label
  • exited
  • status
  • ancestor
  • since
  • volume
  • publish
  • health
  • isolation

I have created a container that is named nextcloud_server. I want to see details about containers, but only those with the name I am looking for. Let us see how to use the name filter.

$ docker ps --filter "name=nextcloud_server"
CONTAINER ID   IMAGE       COMMAND                  CREATED       STATUS       PORTS                                   NAMES
58c7013a49c3   nextcloud   "/entrypoint.sh apac…"   3 hours ago   Up 3 hours   0.0.0.0:8010->80/tcp, :::8010->80/tcp   nextcloud_server

I have several containers running, but passing using the name filter only shows me the containers that match the name.

Let us try using the id filter. I have a MariaDB container with the ID "140161b8b139". I will use the following command to achieve that.

$ docker ps --filter "id=140161b8b139"
CONTAINER ID   IMAGE     COMMAND                  CREATED        STATUS        PORTS      NAMES
140161b8b139   mariadb   "docker-entrypoint.s…"   15 hours ago   Up 15 hours   3306/tcp   nextcloud_db

Easy! I got the container with the matched ID.

Show containers in the order they were created

Yes, you can list containers sorted in the order of their creation date using the --latest (or l for short).

The order is latest on the top and oldest on the bottom.

Here is a sample output of running the command docker ps --latest on my computer:

$ docker ps --latest
CONTAINER ID   IMAGE                              COMMAND                  CREATED        STATUS                      PORTS                                   NAMES
58c7013a49c3   nextcloud                          "/entrypoint.sh apac…"   15 hours ago   Up 15 hours                 0.0.0.0:8010->80/tcp, :::8010->80/tcp   nextcloud_server
73a6901a4846   lscr.io/linuxserver/transmission   "/init"                  16 hours ago   Exited (137) 16 hours ago                                           transmission_web

There are a few gotchas with this command.

  • Any containers that are used as a "dependency" will not be listed
  • The output includes all container states (that means even containers that are stopped will be listed)

I had created the container "nextcloud_server" with MariaDB as its "dependency." So that container is not listed in the output when using --latest flag.

Scripting much? Show only container IDs

Assume you are writing a script and only want to deal with Container IDs so you can perform actions on containers. For that, you can use the --quiet (or -q for short) option.

Given below is the output of running docker ps -q on my computer.

$ docker ps -q
58c7013a49c3
140161b8b139

As you can see, the output consists only of Container IDs (of containers that are running) and nothing else.

As you can see, there is more to the Docker ps command than just displaying the running container information. Let me know if you learned something new or if you know some other useful example of the docker ps command.