Listing containers (docker ps, docker ps -a) - Deep Dive

Overview - Listing containers (docker ps, docker ps -a)

What is it?

Listing containers means showing which Docker containers are currently on your system. The command 'docker ps' shows only running containers, while 'docker ps -a' shows all containers, including those stopped. This helps you see what containers exist and their status at a glance.

Why it matters

Without being able to list containers, you wouldn't know which containers are running or stopped, making it hard to manage or troubleshoot your Docker environment. It’s like trying to find a parked car without a parking lot map. This command helps you keep track of your containers easily.

Where it fits

Before learning this, you should understand what Docker containers are and how to start or stop them. After this, you can learn how to inspect container details, manage container logs, or remove containers.

Mental Model

Core Idea

Listing containers is like checking a list of cars in a parking lot to see which are parked and which are currently driving.

Think of it like...

Imagine a parking lot where some cars are parked and some are driving around. 'docker ps' shows only the cars currently driving, while 'docker ps -a' shows every car that has ever been in the lot, whether parked or driving.

┌───────────────────────────────┐
│ Docker Containers Listing      │
├───────────────┬───────────────┤
│ docker ps     │ Running only  │
│ docker ps -a  │ All containers│
└───────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Docker container?

Concept: Understand the basic unit you will list: a Docker container.

A Docker container is a lightweight, standalone package that includes everything needed to run a piece of software. Think of it as a small box that holds an app and its environment. Containers can be running or stopped.

Result

You know what containers are and why you might want to see them.

Understanding what containers are is essential before listing them, because listing only makes sense if you know what you are looking for.

2

Foundation

Starting and stopping containers

Concept: Learn how containers can be running or stopped, which affects listing.

You can start a container with 'docker run' and stop it with 'docker stop'. Running containers are active; stopped containers are inactive but still exist on your system.

Result

You can create containers and change their state, which affects what 'docker ps' shows.

Knowing container states helps you understand why some containers appear or disappear in listings.

3

Intermediate

Using 'docker ps' to list running containers

🤔Before reading on: do you think 'docker ps' shows all containers or only running ones? Commit to your answer.

Concept: 'docker ps' lists only containers that are currently running.

Run 'docker ps' in your terminal. It will show a table with container ID, image, command, creation time, status, ports, and names, but only for running containers.

Result

You see a list of active containers with useful details.

Understanding that 'docker ps' filters to running containers helps you quickly check what is active without clutter.

4

Intermediate

Using 'docker ps -a' to list all containers

🤔Before reading on: does 'docker ps -a' show only running containers or all containers? Commit to your answer.

Concept: 'docker ps -a' lists all containers, including stopped ones.

Run 'docker ps -a' in your terminal. It shows the same table as 'docker ps' but includes containers that are stopped, exited, or paused.

Result

You see every container on your system, regardless of state.

Knowing how to see all containers helps you manage and clean up containers that are not running.

5

Intermediate

Understanding container status in listings

Concept: Learn what the status column means in 'docker ps' output.

The STATUS column shows if a container is Up (running), Exited (stopped), or Paused. It also shows how long ago the status changed, e.g., 'Up 5 minutes' or 'Exited (0) 2 hours ago'.

Result

You can interpret container states from the listing easily.

Reading status correctly helps you decide which containers need attention or cleanup.

6

Advanced

Filtering and formatting container listings

🤔Before reading on: do you think you can customize 'docker ps' output to show only certain containers or fields? Commit to your answer.

Concept: 'docker ps' supports filters and custom output formats to tailor listings.

You can use flags like '--filter' to show containers by status or name, e.g., 'docker ps --filter status=exited'. You can also format output with '--format', e.g., 'docker ps --format "{{.ID}}: {{.Names}}"' to show only IDs and names.

Result

You get customized container lists suited to your needs.

Knowing filtering and formatting makes container management efficient and scriptable.

7

Expert

How Docker tracks containers for listing

🤔Before reading on: do you think Docker stores container info in a database or reads live system state for 'docker ps'? Commit to your answer.

Concept: Docker maintains container metadata and state in its internal storage, which 'docker ps' queries to show listings.

Docker stores container info in a local database and tracks runtime state via the container runtime. 'docker ps' reads this metadata and runtime info to display container lists quickly without scanning the entire system.

Result

You understand why 'docker ps' is fast and reliable even with many containers.

Knowing Docker's internal tracking explains how listing commands remain efficient and consistent.

Under the Hood

'docker ps' queries Docker's internal container metadata store and runtime state. It combines static info like container ID, image, and creation time with dynamic state like running or exited. This data is fetched from Docker's container runtime and stored metadata, then formatted into a table for display.

Why designed this way?

Docker separates container metadata from runtime state to allow fast queries and reliable state tracking. This design avoids scanning the entire filesystem or processes, making listing commands quick and scalable. Alternatives like scanning processes would be slow and error-prone.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Container    │       │ Docker Engine │       │ Terminal/User │
│ Metadata DB  │◄─────►│ Runtime State │◄─────►│ Runs 'docker' │
└───────────────┘       └───────────────┘       └───────────────┘
        ▲                      ▲                      ▲
        │                      │                      │
        └───────────────┬──────┴───────┬──────────────┘
                        │              │
                 'docker ps'      'docker ps -a'
                 queries combined container info

Myth Busters - 4 Common Misconceptions

Quick: Does 'docker ps' show stopped containers? Commit yes or no before reading on.

Common Belief: 'docker ps' shows all containers, running or stopped.

Reality: 'docker ps' shows only running containers by default; stopped containers are not listed unless you add '-a'.

Why it matters: Assuming 'docker ps' shows all containers can cause you to miss stopped containers that may need cleanup or inspection.

Quick: Does 'docker ps -a' remove containers? Commit yes or no before reading on.

Common Belief: 'docker ps -a' deletes stopped containers from the system.

Reality: 'docker ps -a' only lists all containers; it does not delete or modify them.

Why it matters: Confusing listing with deletion can lead to accidental data loss if users try to 'clean' containers incorrectly.

Quick: Does the STATUS column in 'docker ps' always mean the container is currently running? Commit yes or no before reading on.

Common Belief: If a container has a STATUS, it means it is running.

Reality: STATUS shows the last known state, which can be 'Exited' or 'Paused' as well as 'Up'.

Why it matters: Misreading STATUS can cause confusion about container availability and lead to wrong operational decisions.

Quick: Does 'docker ps' scan the entire system processes to find containers? Commit yes or no before reading on.

Common Belief: 'docker ps' scans all system processes to find containers.

Reality: 'docker ps' uses Docker's internal metadata and runtime info, not a system-wide process scan.

Why it matters: Believing it scans all processes can lead to misunderstanding performance and reliability of Docker commands.

Expert Zone

1

The order of containers listed by 'docker ps' is by creation time descending, which helps quickly find recent containers.

2

'docker ps' output can be scripted and parsed using '--format' for automation in CI/CD pipelines.

3

Docker's internal metadata store is updated asynchronously, so very recent container state changes might not appear instantly in 'docker ps'.

When NOT to use

'docker ps' is not suitable for deep container inspection or logs; use 'docker inspect' or 'docker logs' instead. For system-wide process monitoring, use OS tools like 'ps' or 'top'.

Production Patterns

In production, 'docker ps' is used in monitoring scripts to check container health, in cleanup scripts with filters to remove exited containers, and in dashboards to show container status summaries.

Connections

Process Management in Operating Systems

'docker ps' is similar to 'ps' command that lists running processes.

Understanding OS process listing helps grasp how Docker abstracts container processes and presents them in a user-friendly way.

Database Querying

'docker ps' queries Docker's internal metadata store like a database query.

Knowing database querying concepts clarifies how filtering and formatting options in 'docker ps' work efficiently.

Inventory Management

Listing containers is like managing inventory items with statuses (in stock, sold, returned).

Inventory management principles help understand why tracking container states and history is important for system health.

Common Pitfalls

#1 Trying to see all containers with just 'docker ps' and wondering why stopped containers are missing.

Wrong approach:

docker ps

Correct approach:

docker ps -a

Root cause:

Misunderstanding that 'docker ps' defaults to showing only running containers.

#2 Assuming 'docker ps -a' deletes stopped containers and running it to clean up space.

Wrong approach:

docker ps -a

Correct approach:

docker container prune

Root cause:

Confusing listing commands with cleanup commands.

#3 Ignoring the STATUS column and assuming all listed containers are active.

Wrong approach:

docker ps -a
# then treat all containers as running

Correct approach:

docker ps -a
# check STATUS column before acting

Root cause:

Not reading container state carefully leads to wrong operational decisions.

Key Takeaways

The 'docker ps' command lists only running containers by default, helping you see active workloads quickly.

'docker ps -a' expands this to show all containers, including stopped ones, giving a full picture of your Docker environment.

Understanding container states and the STATUS column is crucial to interpret listings correctly and manage containers effectively.

Docker uses an internal metadata store and runtime state to provide fast and reliable container listings without scanning the entire system.

Filtering and formatting options in 'docker ps' enable powerful customization for automation and production use.