Docker

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

docker list containers

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.

Why does listing Docker containers matter?

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.

How to list Docker containers

1. Listing running Docker containers

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

$ docker ps
CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS       PORTS                                                                      NAMES
ed814bb3cbb4   portainer/portainer-ce   "/portainer"             6 weeks ago     Up 6 weeks   8000/tcp, 9000/tcp, 9443/tcp                                               portainer
3d33792a8ce1   traefik:1.7              "/traefik --acme.ema…"   9 months ago    Up 6 weeks   0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   traefik
ed7100c0f6f0   mysql:5.7                "docker-entrypoint.s…"   10 months ago   Up 6 weeks   3306/tcp, 33060/tcp                                                        village-mysql-1
0a83e509c252   wordpress                "docker-entrypoint.s…"   10 months ago   Up 6 weeks   80/tcp                                                                     village-wordpress-1

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.

2. Listing all Docker containers

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:

$ docker ps -a
CONTAINER ID   IMAGE                      COMMAND                  CREATED         STATUS                     PORTS                                                                      NAMES
2efb282237a6   nginx:latest               "/docker-entrypoint.…"   5 seconds ago   Exited (0) 2 minutes ago                                                                               serene_black
ed814bb3cbb4   portainer/portainer-ce     "/portainer"             6 weeks ago     Up 6 weeks                 8000/tcp, 9000/tcp, 9443/tcp                                               portainer
3d33792a8ce1   traefik:1.7                "/traefik --acme.ema…"   9 months ago    Up 6 weeks                 0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   traefik
ed7100c0f6f0   mysql:5.7                  "docker-entrypoint.s…"   10 months ago   Up 6 weeks                 3306/tcp, 33060/tcp                                                        village-mysql-1
0a83e509c252   wordpress                  "docker-entrypoint.s…"   10 months ago   Up 6 weeks                 80/tcp                                                                     village-wordpress-1

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.

 

3. Listing most recently created Docker containers

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

$ docker ps -l
CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS                     PORTS     NAMES
2efb282237a6   nginx:latest   "/docker-entrypoint.…"   5 minutes ago   Exited (0) 5 minutes ago             serene_black

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

# List the 3 most recently created containers
$ docker ps -n 3
CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS                     PORTS                                                                      NAMES
2efb282237a6   nginx:latest             "/docker-entrypoint.…"   7 minutes ago   Exited (0) 7 minutes ago                                                                              serene_black
ed814bb3cbb4   portainer/portainer-ce   "/portainer"             6 weeks ago     Up 6 weeks                 8000/tcp, 9000/tcp, 9443/tcp                                               portainer
3d33792a8ce1   traefik:1.7              "/traefik --acme.ema…"   9 months ago    Up 6 weeks                 0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   traefik

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.

4. Using output options when listing Docker containers

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:

$ docker ps -q
ed814bb3cbb4
3d33792a8ce1
ed7100c0f6f0
0a83e509c252

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.

$ docker ps --no-trunc
CONTAINER ID                                                       IMAGE                    COMMAND                                       CREATED         STATUS       PORTS                                                                      NAMES
ed814bb3cbb41b639cbb8142a5c2e62c3a278855ae17992f29b915b640da4e8b   portainer/portainer-ce   "/portainer"                                  6 weeks ago     Up 6 weeks   8000/tcp, 9000/tcp, 9443/tcp                                               portainer
3d33792a8ce12c50e8885113d85462a9700415b819395a952921b126a27724f6   traefik:1.7              "/traefik --acme.email=admin@example.com"     9 months ago    Up 6 weeks   0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   traefik
ed7100c0f6f0a63e3cdfb8c9ea083a883e3993bbd9c98eb033884a38b26132e6   mysql:5.7                "docker-entrypoint.sh mysqld"                 10 months ago   Up 6 weeks   3306/tcp, 33060/tcp                                                        village-mysql-1
0a83e509c2521c0c63e9e542047b4783f968bd74f7f0252c08344f8a04cbea31   wordpress                "docker-entrypoint.sh apache2-foreground"     10 months ago   Up 6 weeks   80/tcp                                                                     village-wordpress-1

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:

$ docker ps -s
CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS       PORTS                                                                      NAMES                        SIZE
ed814bb3cbb4   portainer/portainer-ce   "/portainer"             6 weeks ago     Up 6 weeks   8000/tcp, 9000/tcp, 9443/tcp                                               portainer                    0B (virtual 294MB)
3d33792a8ce1   traefik:1.7              "/traefik --acme.ema…"   9 months ago    Up 6 weeks   0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   traefik                      0B (virtual 82.9MB)
ed7100c0f6f0   mysql:5.7                "docker-entrypoint.s…"   10 months ago   Up 6 weeks   3306/tcp, 33060/tcp                                                        village-mysql-1              4B (virtual 455MB)
0a83e509c252   wordpress                "docker-entrypoint.s…"   10 months ago   Up 6 weeks   80/tcp                                                                     village-wordpress-1          2B (virtual 615MB)

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:

$ docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}"
CONTAINER ID   NAMES                    STATUS
ed814bb3cbb4   portainer                Up 6 weeks
3d33792a8ce1   traefik                  Up 6 weeks
ed7100c0f6f0   village-mysql-1          Up 6 weeks
0a83e509c252   village-wordpress-1      Up 6 weeks

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.

5. Docker ps command alternatives

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.

6. Listing Docker containers from Docker Compose projects

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.

$ docker compose ps
NAME                         IMAGE       COMMAND                                     SERVICE     CREATED         STATUS       PORTS
village-mysql-1              mysql:5.7   "docker-entrypoint.sh mysqld"               mysql       10 months ago   Up 6 weeks   3306/tcp, 33060/tcp
village-wordpress-1          wordpress   "docker-entrypoint.sh apache2-foreground"   wordpress   10 months ago   Up 6 weeks   80/tcp

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.

$ docker compose ls
NAME                  STATUS        CONFIG FILES
village               running(2)    /home/jh_walker/apps/village/docker-compose.yml
docker-web-platform   running(2)    /home/jh_walker/docker-web-platform/docker-compose.yml

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.

Key points

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.

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

Docker CLI Commands Cheat Sheet

Grab our ultimate cheat sheet PDF

for all the Docker commands you need.

docker book
Share your data and download the cheat sheet