docker ps
100%

Docker · Lesson 4

docker ps

Learn how to list Docker containers and tell which ones are running or have exited.

Is the web server you started in Docker still running? Use docker ps to check. A Docker image packages the program and the files it needs. A container is an instance created from that image. The command shows the container list as it looks when you run it.

Listing Running Containers

By default, docker ps lists running containers. The examples show a few columns from a prepared Docker environment, so you can read the output without setting up Docker. In a terminal, type the command after the $ prompt.

$ docker ps
IMAGE         STATUS         NAMES
nginx:alpine  Up 4 minutes   web
nginx:alpine  Up 30 seconds  demo

If Docker prints just the column headers, its running-container list is empty. The same environment can still contain containers that have stopped.

Docker prints only the column headers after you run docker ps. What can you tell from that output?

Reading Names and Status

Start with NAMES to find the container you want. Both rows show the same image, nginx:alpine, in the IMAGE column. Find web in the rightmost column, then read STATUS on that row. Up 4 minutes means that container has been running for about four minutes.

Which row describes a container that has been running for about 30 seconds?

Including Exited Containers

If a container you expect is missing, try docker ps -a. The -a option is short for --all. It includes containers that have stopped and still exist. This example also includes a prepared task named preview.

$ docker ps -a
IMAGE         STATUS                         NAMES
nginx:alpine  Up 4 minutes                   web
nginx:alpine  Up 30 seconds                  demo
busybox:1.36  Exited (0) 2 minutes ago       report
busybox:1.36  Exited (1) About a minute ago  preview

A container runs a main program, such as a web server or a script. Exited means that program has stopped. The number in parentheses is its exit code, the result it reported when it stopped. Zero usually means success, and a nonzero code usually indicates an error. The report task shows Exited (0), a normal result for a task that finished successfully.

LabEx Terminal showing running and exited containers with report at exit code 0 and preview at exit code 1

The LabEx capture lists just the names and states of the four example containers. Elapsed times depend on when you run the command.

Which row would you investigate for an error, based on its exit code?

Choosing the Next Check

An exit code helps you decide where to look. To see whether preview printed an error message, use docker logs followed by its name. This shows the output Docker collected from that container.

$ docker logs preview

For a running web server, you may also want to know whether a visitor can open its page. To check that, open the page from the computer that needs to reach it. Up describes the program inside the container. A successful browser request confirms that the page is reachable from where you tested.

The page opens on the computer running Docker. A coworker needs to open it from another computer. Which check tells you whether they can?

Lesson complete

You finished docker ps

You can now use the container list to identify a container, read its state, and choose what to check next.

  • Use docker ps to list running containers.

  • Find a container by name and read its status.

  • Use docker ps -a to include exited containers.

  • Use logs or a browser request to answer questions the status alone cannot resolve.

Keep your learning progress

Create a free account to save this lesson and continue learning on any device.

Create a free account
Next Lesson
Back to Docker