Solving the DevOps Infrastructure Dilemma: Enabling developer velocity with control đź’ˇ

Register for the webinar here →

Docker

Docker Ps Command – When to Use & Examples

Docker Ps Command

Docker is the leading platform for developers working with containerized apps. It gives you everything you need to build and run containers that package your apps and their dependencies into isolated units. However, getting to know Docker’s feature-packed CLI can be daunting to newcomers and seasoned users alike.

In this article, we’ll examine one of the most important Docker commands: docker ps, for listing the containers that exist on your host. We’ll share examples and best practices that’ll help you efficiently work with the command. Let’s get started.

We will cover:

  1. What is docker ps?
  2. When to use docker ps?
  3. How to use docker ps command – examples
  4. How to filter docker ps output
  5. How to format docker ps options with JSON
  6. Docker ps alternatives
  7. Best practices and tips for using docker ps

What is docker ps?

docker ps provides a list of the Docker containers on your machine. You can use it to check whether a container is running, display container sizes, and find stopped containers that you need to restart or remove. It’s the best way to monitor all your containers, without having to individually retrieve them by ID or name.

The docker ps command is named because it has a similar purpose to the Unix ps command. ps shows the processes running on your host, while docker ps shows your containers. In fact, as it’s good practice for containers to only run a single process, docker ps is directly analogous to ps—each container it displays represents a distinct process on your host.

When to use docker ps?

You can reach for docker ps in any of these situations:

  • Viewing running containers.
  • Viewing stopped containers.
  • Checking a container’s ID or name.
  • Listing all open container port bindings.
  • Inspecting container filesystem sizes.
  • Checking whether containers are healthy.

In summary, docker ps is the right Docker command whenever you need to monitor multiple containers or check what’s running on your host.

How to use docker ps command - Examples

Let’s use some examples to see the different docker ps command variants and options in action.

Example 1 – Basic usage: docker ps

Running docker ps without any arguments will show just the containers that are currently running on your host.

CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS                  PORTS     NAMES
510a7ab9b507   nginx:latest   "/docker-entrypoint.…"   1 second ago   Up Less than a second   80/tcp    silly_galois

You’ll see tabulated output that shows the ID, image, running command, age, and status of your containers, as well as each container’s name and any applicable port bindings.

Example 2 – Using docker ps to view stopped containers

Docker containers can be stopped and then restarted at a later time. Stopped containers retain their configuration but don’t actively run any processes on your host. They’re excluded from docker ps output by default.

To include these containers, add the -a or --all flag to your command:

$ docker ps -a
CONTAINER ID   IMAGE                                      COMMAND                  CREATED        STATUS                      PORTS     NAMES
510a7ab9b507   nginx:latest                               "/docker-entrypoint.…"   21 hours ago   Exited (127) 21 hours ago             silly_galois

Containers that have stopped will show their exit code in the STATUS column. This can help you debug errors that cause containers to stop unexpectedly. In the example above, the exit code 127 indicates that an invalid command was specified for the container process.

Example 3 – Using docker ps to view your most recently created containers

Sometimes it’s helpful to only see the containers that have been most recently created on your host. You can achieve this by setting the -n or --last flag, which constrains the docker ps output so that no more containers are displayed than the number that you specify:

# Get the 2 most recently created containers
$ docker ps --last 2
CONTAINER ID   IMAGE                                      COMMAND                  CREATED        STATUS                      PORTS     NAMES
510a7ab9b507   nginx:latest                               "/docker-entrypoint.…"   21 hours ago   Exited (127) 21 hours ago             silly_galois
2dd9ad8d047a   mysql:8.0                                  "docker-entrypoint.s…"   9 days ago   Exited (0) 2 days ago               abc0822b-mysql-1

Note that the -n/--last flag automatically implies -a/--all too: stopped containers will also appear in the output, if they match your selection.

Example 4 – Using docker ps to get just the most recently created container

The -l/--latest flag is an even quicker way to inspect the single most recent container created on your host. It’s equivalent to using -n 1.

$ docker ps --latest
CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS                      PORTS     NAMES
510a7ab9b507   nginx:latest   "/docker-entrypoint.…"   22 hours ago   Exited (127) 21 hours ago             silly_galois

This is a great way to check whether a just-created container has started correctly. You don’t have to type the container’s ID or name.

Example 5 – Using docker ps to inspect container sizes

Monitoring container sizes can help prevent Docker from consuming an excessive amount of storage. To view container size information in docker ps, include the -s or --size flag with your command:

$ docker ps
CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS     NAMES              SIZE
96aa69c116df   nginx:latest   "/docker-entrypoint.…"   2 minutes ago   Up 2 minutes   80/tcp    eloquent_khayyam   1.09kB (virtual 187MB)

Two values are displayed in the SIZE column: the first gives the size of the container’s writable filesystem layer, while the “virtual” size represents the disk space used by the container’s image.

As images are shared among multiple containers, their sizes don’t directly count towards individual container sizes. However, they still affect the total amount of storage required to run that container, so they’re included in the docker ps output.

Example 6 – Using docker ps to only show container IDs

Sometimes you might not need access to all the container details displayed by docker ps. If you only want to know which containers match a query, you can use the -q flag to make docker ps emit a list of container IDs, without including any of the other default output fields.

$ docker ps -q
96aa69c116df
510a7ab9b507
5529b7a432b2
2dd9ad8d047a

How to filter docker ps output

You can filter docker ps output using several different conditions including container labels, status, creation time, exposed Docker ports, and health check results.

Here are a few examples.

1. Get containers with a label

$ docker ps --filter label=app=my-app

This option is helpful when you’re using labels to distinguish containers belonging to different projects, components, or environments.

2. Get containers created before/since another container

$ docker ps --filter since=my-app-container

3. Get containers that are using a particular volume

$ docker ps --filter volume=my-volume

4. Get containers joined to a specific network

$ docker ps --filter network=my-network

How to format docker ps options with JSON

docker ps defaults to presenting its output in the table format shown in the previous examples. You can create your own format instead by using Go template syntax. Both standalone and table-based templates are supported, using --format 'TEMPLATE' and --format 'table TEMPLATE' syntax respectively.

# Display container IDs, images, and statuses in a table
$ docker ps --format 'table {{.ID}}\t{{.Image}}\t{{.Status}}'
CONTAINER ID   IMAGE                                             STATUS
86331e59e578   mysql:8.0                                         Up 2 months
ade1ce2eb1e8   portainer/portainer-ce                            Up 3 months

docker ps also supports JSON output when you set the --format json flag. This will print a new JSON record for each of your containers. The fields included in the JSON include the container IDs, creation times, images, labels, names, ports, and statuses, in addition to other information such as volume mounts and networks.

Docker ps alternatives

It’s worth mentioning there are several aliases for docker ps that work in exactly the same way:

  • docker container ls
  • docker container list
  • docker container ps

These are newer, more expressive alternatives from the Docker container command group.

Getting more information about your containers

docker ps is designed to let you quickly view key details about the containers that exist on your Docker host. You can get more detailed information about individual containers by reaching for docker inspect. This command takes a container ID or name as an argument, and then displays the complete JSON representation of that container:

$ docker inspect 510a7ab9b507
{
    "Id": "510a7ab9b507595e36a9a22e86c128aeabfe65d2bca809f8a2b4ccbe1ee9e6e5",
    "Created": "2023-10-12T20:28:41.797219004Z",
    "Path": "/docker-entrypoint.sh",
    "Args": [
        "-p",
        "8080:80"
    ],
    ...

Best practices and tips for using docker ps

docker ps is a fundamental Docker feature. As it’s likely to be one of your most-used commands, it’s helpful to pay attention to its options and remember some quick tips:

  1. Only use -a when you need to view stopped containers — In general, you’ll usually want to interact with actively running containers. Omitting the -a flag will reduce the visual noise of seeing stopped containers in your output.
  2. Use custom formatters — Custom formatting templates let you select the information you want to see. Setting up shell aliases that automatically apply your frequently used filters can save you some time.
  3. Set up aliases for filters too — Similarly, shortcuts to frequently used filter combinations will help you effectively use docker ps as you work across different projects.

Key points

The docker ps command lists the Docker containers that are running on your host. It’s one of the most frequently used Docker CLI commands so understanding its various options will help improve your everyday container management experience. Throughout this article, we’ve seen how features such as filters and formatters make it easier and more efficient to interact with your containers.

We encourage you also to explore how integrating with third party tools is easily done at Spacelift. You have the possibility of installing and configuring them before and after runner phases or you can simply bring your own Docker image and leverage them directly.

The Most Flexible CI/CD Automation Tool

Spacelift is an alternative to using homegrown solutions on top of a generic CI. It helps overcome common state management issues and adds several must-have capabilities for infrastructure management.

Start free trial

The Practitioner’s Guide to Scaling Infrastructure as Code

Transform your IaC management to scale

securely, efficiently, and productively

into the future.

ebook global banner
Share your data and download the guide