Docker Ps Command – When to Use & Examples

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

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.

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.

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.

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:

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:

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.

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:

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.

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

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

3. Get containers that are using a particular volume

4. Get containers joined to a specific network

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.

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.

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

The docker ps command lists the 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.