3.1 Basics of the docker ps Command
The docker ps command is one of the most useful ones in the Docker arsenal. It displays a list of running containers and provides information about them. In this lecture, we'll dive into how to use docker ps to check the status of your containers and what options are available for more detailed output.
By default, the docker ps command outputs only the list of containers that are currently running.
Syntax
docker ps [OPTIONS]
Where:
-
OPTIONS: additional options for filtering and formatting the output.
Basic Usage Example
docker ps
This basic call of the docker ps command will display a list of all running containers. The output will include the following fields:
- CONTAINER ID: unique identifier of the container.
- IMAGE: image that the container was created from.
- COMMAND: command being executed in the container.
- CREATED: time elapsed since the container was created.
- STATUS: current status of the container (e.g., Up 5 minutes).
- PORTS: exposed ports.
- NAMES: name of the container.
List All Containers
To display all containers, including stopped ones, use the -a option:
docker ps -a
This command will show a list of all containers that have ever run, indicating their current state (running, stopped, etc.).
3.2 Filtering Output
Docker lets you filter the output of the docker ps command to show only those containers that match specific criteria.
1. Filtering by Status
For example, to show only stopped containers:
docker ps -f "status=exited"
2. Filtering by Name
To display containers with a specific name or part of it:
docker ps -f "name=my_container"
3. Filtering by Image
To show containers created from a specific image:
docker ps -f "ancestor=nginx"
3.3 Output Formatting
You can customize the output of the docker ps command to make it more readable or include only the fields you need. For this, the --format parameter is used.
Formatting Example
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}"
This example outputs a table with the container ID, its name, and its status.
Available Table Columns
- {{.ID}}: container ID.
- {{.Image}}: container image.
- {{.Command}}: command running in the container.
- {{.CreatedAt}}: container creation time.
- {{.RunningFor}}: how long the container has been running.
- {{.Status}}: current container state.
- {{.Ports}}: forwarded ports.
- {{.Names}}: container name.
Usage Examples
Example 1: displaying only container IDs
This example will output only the IDs of running containers. Useful for use in scripts.
docker ps -q
Example 2: displaying containers started in the last 24 hours
docker ps --filter "since=24h"
Example 3: displaying containers with a specific status and formatting the output
This example will output a table with container names, their statuses, and forwarded ports for all running containers.
docker ps -f "status=running" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
3.4 Practical Scenarios
1. Monitoring Running Containers
When you’ve got multiple containers running, the docker ps command lets you quickly check their current status and make sure everything’s working fine.
docker ps
2. Finding and Removing Stopped Containers
When containers stop running, they stay in the system until you delete them. You can use docker ps -a to find all stopped containers and then remove them.
docker ps -a -f "status=exited"
docker rm $(docker ps -a -f "status=exited" -q)
3. Automating Tasks
Using the docker ps command in scripts lets you automate various container admin tasks. For example, you can create container status reports or automatically restart containers if they’re stopped.
if [ $(docker ps -q -f "name=my_container") ]; then
echo "Container is running"
else
docker start my_container
fi
Important! This “code” is written for the Linux terminal. You might need to check it out.
GO TO FULL VERSION