Introduction to Docker List Containers
The ‘Docker List Containers’ command, accessible through ‘docker container ls’ or the shorthand ‘docker ps’, is an essential tool in Docker’s container management suite. Its primary function is to offer a comprehensive snapshot of all containers currently running on a Docker host. When executed, it provides valuable information such as Container ID, Image name, executing Command, Creation Time, Status, Ports in use, and Names of the containers.
This command is not only about listing containers; it’s a versatile tool for monitoring the health and state of containers, assisting in resource optimization, facilitating troubleshooting, and ensuring security by identifying any unauthorized or suspicious containers. It comes with several valuable flags like -a or –all to show all containers, –format for custom output, -q or –quiet for displaying only container IDs, and –no-trunc to prevent output truncation. Understanding and utilizing this command is crucial for anyone involved in Docker container management, as it provides critical insights necessary for maintaining an efficient and secure Docker environment.
Table of Contents:
- Introduction to Docker List Containers
- Docker help command
- Quiet mode command
- Docker start command
- Docker run command
- The docker build command
- Advanced Filtering in Listing
- Exit Codes
- The –format
- Docker inspect command
- The n command
Syntax:
"docker container ls" or "docker ps"
Output:
What do the above columns mean?
- CONTAINER ID: This column represents a unique identifier assigned to each Docker container. It’s a hexadecimal string that uniquely identifies the container instance. Users often refer to containers using their Container ID.
- IMAGE: The IMAGE column displays the name or identifier of the Docker image used to create the container. An image is a lightweight, standalone, and executable package with everything needed to run the software, including the code, runtime, libraries, and system tools.
- COMMAND: The COMMAND column shows the command used to start the container. It specifies the initial command executed when the container starts. For example, it might indicate the primary process or script within the container.
- CREATED: This column shows the time elapsed since the container’s creation. It offers information about the instantiation time of the container from its corresponding image.
- STATUS: The STATUS column reflects the container’s current state. It could indicate that the container is running, stopped, paused, or experiencing a problem.
- PORTS: The PORTS column lists the ports the container exposes and maps to the host system, offering information on external access to the container’s services.
- NAMES: The NAMES column shows the human-readable name assigned to the container. Docker automatically gives a unique name to each container unless a specific name is provided during container creation.
Docker ps -a command:
It lists all the containers on the host machine, including the stopped containers.
Syntax:
docker ps -a or docker ps --all
Output:
Explanation: In the “Status” column, it indicates “Exited (1) 32 minutes ago.” This message signifies that the container named “brave_meitner” was stopped 32 minutes ago.
Docker help command
Syntax:
$docker container ls –help
Output:
Docker ps help command:
Syntax:
docker ps --help
Output:
Docker ps –no-trunc command:
The docker ps –no-trunc command displays container information without truncating the output. By default, the docker ps command shortens the container IDs, making them easier to read but potentially losing some uniqueness. The –no-trunc option turns off this truncation, showing the full container IDs.
Syntax:
docker ps –no-trunc
Output:
Docker ps –size command:
The docker ps –size command is used to display additional information about the disk space usage of containers. Including the –size option with the docker ps command adds a “SIZE” column to the output, indicating the amount of data space the container uses on the host system. The size is typically displayed in human-readable format, making it easier to understand the space consumption.
Syntax:
docker ps –size
Output:
Quiet mode command
The docker container ls -q command is used to list only the IDs of the running containers. It prints only the container IDs in a single column.
Syntax:
docker ps -q
Output:
We can also use the quiet command in combination with the Truncate command to see the entire container id’s
Docker start command
The docker start command starts one or more stopped containers.
Syntax:
docker start [OPTIONS] CONTAINER [CONTAINER...]
- OPTIONS: Additional configuration options for starting the container include attaching to it or allocating a pseudo-TTY.
- CONTAINER: The ID or name of the container to start. You can specify multiple containers separated by space.
Output:
Docker run command
The Docker run command launches a new container based on a specified Docker image.
Syntax:
docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
- OPTIONS: Additional configuration options for the container, such as specifying ports, volumes, environment variables, and more.
- IMAGE: The Docker image from which the container will be created.
- COMMAND: The command to run inside the container. If not specified, the default command defined in the Docker image is used.
- ARG: Additional arguments passed to the command specified in the container.
The docker build command
The docker build command creates Docker images from a Docker file and context.
Syntax:
docker build [OPTIONS] PATH | URL | -
- OPTIONS: Additional configuration options for the build process, such as specifying a tag for the image, setting build-time variables, specifying the Dockerfile location, and more.
- PATH | URL | -: The build context. It can be a local directory path, a URL to a Git repository, or a single hyphen (–) to read the build context from the standard input.
Advanced Filtering in Listing
We can use the filter keyword to customize the output of the listings
Example 1
Syntax:
docker container ls --filter "status=exited"
Output:
Example 2
Syntax:
docker container ls --filter "status=paused"
Output:
More filtering tags include:
Filter | Description |
docker ps –filter “id=<container_id>” | Container ID (ID or container): Filters containers by their ID. |
docker ps –filter “name=<container_name>” | Name (name): Filters containers by their name. |
docker ps –filter “status=running” | Status (status): Filters containers by their status (e.g., running, exited). |
docker ps –filter “label=<key>=<value>” | Label (label): Filters containers based on key-value pairs specified as labels. |
docker ps –filter “network=<network_name>” | Network (network): Filters containers by the network they are connected to. |
docker ps –filter “volume=<volume_name>” | Volume (volume): Filters containers by the volume they are using. |
docker ps –filter “health=healthy” | Health (health): Filters containers by their health status. |
docker ps –filter “ancestor=<image_id_or_name>” | Ancestor (ancestor): Filters containers created from a specific image. |
docker ps –filter “before=<container_id_or_name>” | Before (before): Filters containers created before a specified container ID or name. |
docker ps –filter “since=<container_id_or_name>” | Since (since): Filters containers created since a specified container ID or name. |
The status functions are further divided into:
Syntax | Description |
docker ps –filter “status=running” | Filters containers that are currently running |
docker ps –filter “status=exited” | Filters containers that have exited |
docker ps –filter “status=paused” | Filters containers that are currently paused |
docker ps –filter “status=restarting” | Filters containers that are in the process of restarting. |
docker ps –filter “status=dead” | Filters containers that are considered dead. |
docker ps –filter “status=created” | Filters containers that have been created but have yet to be started. |
docker rm <container_id_or_name> | Filters containers that are in the process of being removed |
Exit Codes
When we see the “Exited” status for a Docker container, the container has stopped running. The “Exited” status is accompanied by an exit code in parentheses, indicating the reason for the container’s termination. Here are some common exit codes and their meanings:
Exit Code(s) | Description |
Exited (0) | Container exited successfully |
Exited (1) | Container exited with an error |
Exited (137) | The container was killed with a SIGKILL signal, often indicating it exceeded its allocated resources. |
Exited (143) | Container exited after receiving a SIGTERM signal |
Exited (255) | Container exited with an undefined error or unexpected error. |
The –format
The –format option in Docker commands allows you to format the output according to a Go template. It helps customize how information is displayed when listing containers, images, volumes, networks, or other Docker entities.
Syntax:
docker command --format "TEMPLATE"
- command: The Docker command you are using (e.g., docker ps, docker images).
- –format: The option specifying the Go template to use for formatting.
- “TEMPLATE”: The Go template specifies how the output should be formatted.
The Go template consists of placeholders (fields) enclosed in double curly braces ({{.Field}}). These placeholders are replaced with actual values from the Docker entities being listed.
If we want to display only the container’s ID, then use the –format option as below:
Code:
$docker container ls -a --format "{{.ID}}"
Output:
If we want to output the name with the ID, then we have to add that field as below:
Code:
$docker container ls -a --format "{{.ID}} {{.Names}}"
Output:
We can use the ‘\t’ to make more room between the fields as below:
Code:
$ docker container ls -a --format "{{.ID}} \t {{.Names}}"
Output:
We can use multiple fields at the same time and any symbol if you want, as shown below:
Code:
$docker container ls -a --format "{{.ID}} -> \t {{.Names}} -> \t {{.Status}}"
Output:
We can check labels or any other hidden fields not shown by default when we list the containers.
Code:
$ docker container ls -a --format "{{.ID}} \t {{.Names}} \t {{.Labels}} \t {{.Size}}"
Output:
In the above snapshot, only one container has a label, i.e., type=db.
We can see that the output does not have column headers like ID, Name, Label, etc. We have to use the ‘table’ directives as below:
Code:
$docker container ls -a --format "table {{.ID}} \t {{.Names}} \t {{.Labels}} \t {{.Size}}"
Output:
Docker inspect command
The docker inspect command obtains detailed information about Docker objects, such as containers, images, volumes, networks, or tasks. This command is valuable for troubleshooting, understanding the configuration of Docker objects, and extracting specific details for automation or scripting purposes.
Syntax:
docker inspect [OPTIONS] NAME|ID [NAME|ID...]
- OPTIONS: Additional configuration options for inspecting the object, such as formatting the output using a Go template.
- NAME|ID: The name or ID of the Docker object you want to inspect. You can provide multiple names or IDs separated by spaces.
Example:
Code:
docker inspect welcome-to-docker
Output:
More docker inspect commands are:
Code | Description |
docker inspect my_container | Inspect a Container |
docker inspect my_image | Inspect an Image |
docker inspect my_volume | Inspect a Volume |
docker inspect –format=”{{.Name}}: {{.State.Status}}” my_container | Formatting Output with a Template |
The n command
The -n option is used in various Docker commands to specify a numerical value, typically indicating the number of items to display or process
Code:
docker ps – n1 or docker ps --last
Output:
Conclusion – Docker List Containers
Multiple options can be employed to retrieve a list of containers, with the ‘filter’ and ‘format’ options proving particularly useful. The ‘docker ps’ command is commonly preferred for its simplicity, reducing the need for extensive typing.
FAQs
1. What is the difference between docker ps and docker container ls?
Answer: Both commands (docker ps and docker container ls) are equivalent and can be used interchangeably to list containers.
2. Can I sort the listed containers based on specific criteria?
Answer: Yes, you can use the –sort option with docker ps to sort containers based on various criteria. For example, docker ps –sort=size.
3. Can I list containers in a specific order, such as by creation time or by name?
Answer: Yes, you can use the –sort option with docker ps to specify the sorting order. For example, docker ps –sort=created lists containers by creation time.
4. How do I view detailed information about a specific container, such as its logs?
Answer: Use the docker logs command followed by the container ID or name. For example, docker logs mycontainer displays the logs of the “mycontainer” container.
Recommended Articles
We hope that this EDUCBA information on “Docker List Containers” was beneficial to you. You can view EDUCBA’s recommended articles for more information.