How to List Docker Containers [All, Running, Stopped, and More]

Listing your containers is one of the tasks you’ll most frequently encounter when using Docker. It’s an essential operation to see what’s running, monitor container health, and retrieve a container’s ID or name, ready to pass to other Docker CLI commands.

In this beginner-friendly tutorial, we’ll show several techniques for listing containers with different options. This will help you more efficiently use Docker to manage your containers.

When you’re working with containers, it’s important to be able to check what’s actually running on your system. Active Docker hosts can have hundreds or thousands of containers in different states, such as Running, Stopped, and Unhealthy. You need to be able to see these differences to spot problems and correctly manage your workloads.

Here are some of the main use cases where listing containers helps:

• Check which containers are running — Knowing which containers are running can help you troubleshoot issues and identify unnecessary resource utilization on your host system.
• Retrieve container details — Container details such as ID or name are required to use other Docker commands. You can easily discover these values by listing your containers.
• View port bindings — Containerized apps that use network connections will set up port bindings so you can access the workload inside the container. Listing your containers lets you view which ports are currently in use.
• View container health check results — Container health checks allow Docker to report whether the app inside a container is functioning correctly. Listing your containers lets you monitor health check results and identify any containers with problems.
• Can be used within your own scripts — The ability to list containers with various options can help you write your own scripts that wrap the Docker CLI with additional functionality.
• Check for unexpected, unauthorized, or redundant containers — Listing containers enables auditing of the containers running on your machine. You can find redundant containers that are wasting resources, in addition to any containers that may have been created silently by other users or threat actors.

These scenarios illustrate why you should be familiar with the methods Docker provides for listing containers. Although a simple list might not give you all the information you require, it’s always a useful starting point towards retrieving comprehensive container details using other Docker commands like docker logs and docker inspect.

Let’s look at the commands you can use to learn about the containers on your Docker host.

How to list Docker containers:

1. List running Docker containers
2. List all Docker containers
3. List most recently created Docker containers
4. Use output options when listing Docker containers
5. Use Docker ps command alternatives
6. List Docker containers from Docker Compose projects

To list your running containers, you can use the docker ps command:

The command outputs the main details about the containers that are actively running on your system:

• Container ID — The container’s unique ID. You can pass this ID to other Docker commands, such as to stop the container, restart it, or access its logs.
• Image — Provides the tag or ID of the Docker image that the container is running.
• Command — The command line that started the container’s foreground process.
• Created — The time that’s elapsed since the container was created.
• Status — Indicates whether the container is running, stopped, or exited. If the container has a health check command configured, then the current healthiness will also be displayed here.
• Ports — Lists the ports exposed by the container, including bindings mapped from your host.
• Names — Lists the names assigned to the container. When running other Docker commands, it’s often easier to identify containers by name instead of ID.

This information provides an at-a-glance overview of the containers running on your host.

By default, docker ps omits stopped and exited containers—only the actively running containers are shown. You can access a list that includes all the containers on your host, regardless of their status, by specifying the -a or --all flag with your command:

The command’s output includes another exited container that wasn’t shown before. Hence, the -a flag is useful when you’re looking for containers that have completed their task, experienced an error, or been stopped by a user.

Try using docker ps -l when you need the details of a container you just created:

Alternatively, you can list the last n containers you created by using docker ps -n:

Both these options automatically apply the -a flag. You’ll always see the most recently created containers on your host, even if some of them have stopped or exited.

You don’t always need to see all the information that docker ps displays. Setting the -q (--quiet) flag emits just the container IDs, which can be useful when you’re writing your own scripts that monitor which containers are running:

Conversely, sometimes you might want more details than the truncated docker ps output provides. The --no-trunc option allows you to disable truncation, ensuring full container IDs, names, and command lines are displayed.

Displaying file sizes when listing Docker containers

Another useful flag is -s (--size). This adds an extra column that displays the total file size of each container:

The SIZE column contains two values: the first size is the size of the data added to the writable part of the container’s filesystem. It represents just the new files created by the container on top of its container image. The second part (virtual size) reports the combined size of the writable layer and the image’s read-only layers. The read-only layers could be shared with other containers using the same image, so this isn’t an accurate depiction of actual disk utilization.

Customizing Docker container lists

You can customize the output of docker ps using the --format flag. This accepts a Go template string that lets you extract container field values using simple {{placeholder}} syntax. The following example produces a table with just the ID, name, and status fields displayed:

This mechanism allows you to tailor the container list to the information you require. You can find more information about available formatting options in the Docker documentation.

Filtering Docker container lists

Finally, you can filter lists of containers by key/value field pairs using --filter flags. The supported fields include the following:

• id
• name
• label
• status
• health
• exited
• volume
• network
• publish and expose
• before and since

Here are a few examples:

• docker ps --filter health=healthy --filter label=app=my-app — List only healthy containers that are labeled app: my-app.
• docker ps --filter publish=80 --filter status=running — List the running containers that publish port 80.
• docker ps --filter exited=1 — List the containers that have exited with status code 1.

These options let you finetune your container lists to just the resources relevant to your current task.

The docker ps command is the most commonly used method for listing your containers. However, it has two modern aliases available within the Docker CLI’s container function group:

• docker container list
• docker container ls

The output from these commands is identical to what docker ps provides. docker ps is popular because it’s short and memorable, but preferring docker container list for your scripts and documentation can help reduce ambiguity. It improves accessibility for newcomers working with Docker for the first time.

If you’re using Docker Compose in your projects, then there’s two more useful container list commands to learn.

First, the docker compose ps command lists the containers associated with your current Docker Compose project. You need to run it from a Compose project directory or use Compose’s standard -f flag to reference a valid Compose file.

This command functions similarly to docker ps and accepts some of the same flags, including -a/--all, --filter, --format, and -q/--quiet.

The docker compose ls command can be used to list the Compose projects that exist on your host. This allows you to conveniently discover Compose projects and the config files that define them.

The command shows only running Compose projects by default but you can use the -a/--all flag to include stopped projects too. The --filter, --format, and -q/--quiet flags are also supported.

We’ve walked through how to list the Docker containers and Compose projects running on your host. docker ps, docker compose ps, and docker compose ls are some of the most important Docker commands you’ll use as they allow you to see what’s running and monitor for any potential issues.

We encourage you also to explore how Spacelift offers full flexibility when it comes to customizing your workflow. You have the possibility of bringing your own Docker image and using it as a runner to speed up the deployments that leverage third party tools. Spacelift’s official runner image can be found here.