How to use docker ps

Jonas Scholz

3 min read 25. Nov. 2024

When working with Docker, one of the most common tasks you'll perform is checking the status of your containers. The docker ps command is your go-to tool for this. Let's dive into how you can use it effectively, along with some handy options that can make your life easier.

Basic Usage

To start, docker ps lists all running containers by default. It's a quick way to see what's currently active on your system. Here's a basic example of how you might use it:

docker ps

This command will show you a table with columns like CONTAINER ID, IMAGE, COMMAND, CREATED, STATUS, PORTS, and NAMES. It's a snapshot of what's running right now.

Showing All Containers

If you want to see all containers, including those that are stopped, you can use the -a or --all option:

docker ps -a

This is useful if you're trying to track down a container that's no longer running or if you want to see the full history of containers on your system.

Filtering Containers

Sometimes, you'll want to narrow down the list of containers based on specific criteria. The -f or --filter option lets you do just that. For example, if you want to see containers with a specific name, you could do:

docker ps -f name=nostalgic_stallman

You can filter by a variety of keys like id, name, label, status, and more. For instance, to see only running containers:

docker ps -f status=running

Or if you're interested in containers that use a particular image:

docker ps -f ancestor=ubuntu

Formatting the Output

The default output of docker ps is a table, but you might want to format it differently. The --format option allows you to customize the output using Go templates. For example, to list container IDs and commands in a custom format:

docker ps --format "{{.ID}}: {{.Command}}"

If you prefer JSON output, you can do:

docker ps --format "json"

And if you want a table with specific columns, you can use:

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}"

Other Useful Options

Show the Last Created Containers: Use -n or --last to see the most recently created containers. For example, to see the last 3 containers:
```
docker ps -n 3
```
Show the Latest Created Container: The -l or --latest option shows the most recently created container:
```
docker ps -l
```
Don't Truncate Output: If you want to see full container IDs and other long fields, use --no-trunc:
```
docker ps --no-trunc
```
Display Container Sizes: To see how much disk space each container is using, use -s or --size:
```
docker ps -s
```

Practical Examples

Let's say you're managing a development environment with several containers. You might want to check which containers are running and using a specific image, say nginx. You could use:

docker ps -f ancestor=nginx

Or, if you're troubleshooting and need to find containers that have stopped with a specific exit code, you could filter by exit status:

docker ps -a -f exited=0

This would show you all containers that exited successfully.

Conclusion

The docker ps command is a versatile tool in your Docker toolkit. Whether you're just starting out or managing complex container environments, understanding how to use docker ps with its various options can significantly boost your productivity and help you keep track of your containers effectively.