What Is docker ps?
A complete beginner's guide to the command that lets you see exactly what's happening inside your Docker world — which containers are alive, which have stopped, and everything in between.
Imagine walking into a busy hospital ward. Without a patient board on the wall, you’d have no idea who’s currently being treated in which room, who has already been discharged, or who’s waiting. The patient board gives the entire staff a shared, instant snapshot of reality. In Docker’s world, once you start launching containers, you very quickly lose track of what’s actually running unless you have your own version of that patient board. That board is exactly what this guide is about — docker ps, the command that lists your containers and tells you, at a glance, what state each one is in.
1Why You Need a Way to List Containers
Understanding the problem this command solves before looking at what it actually shows.
Containers Are Invisible Unless You Look
A running container doesn’t announce itself with a visible window or icon the way a desktop application might. It’s a background process, isolated from the rest of your system, quietly doing its work. Once you’ve launched more than one or two containers — perhaps a database, a cache, and a web server — it becomes genuinely difficult to remember which ones are still active, which ones crashed silently, and which ones you meant to stop but forgot about.
Containers without a listing tool are like guests at a large party spread across many rooms of a house, with no host keeping track. You know people came in, but without walking through every single room yourself, you have no idea who’s still there, who already left, and who’s asleep on a couch somewhere.
What docker ps Actually Does
In one sentence: docker ps asks the Docker Engine for a live list of containers on the current machine, along with a compact summary of each one’s identity, status, and configuration. It’s a read-only, non-destructive command — running it never changes anything about any container. It simply reports back what already exists.
2What Information the Listing Actually Shows
Breaking down every piece of information this command reports back to you.
Container ID
A short, unique identifier assigned by Docker to that specific container, used internally to distinguish it from every other container that has ever existed.
Image
The name of the image the container was created from — telling you exactly which blueprint this particular container is a living instance of.
Command
The main process or instruction the container was launched to run, showing what it’s actually doing at its core.
Created
How long ago the container was first created, giving you a sense of its age relative to other containers on the system.
Status
Whether the container is currently running, has exited, is paused, or is restarting — the single most important column for understanding what’s actually alive right now.
Ports
Which container ports are connected to which host ports, showing how external traffic can actually reach whatever is running inside.
Names
The human-readable name assigned to the container — either chosen deliberately, or automatically generated by Docker if nothing was specified.
Every column in this listing answers a different question a beginner naturally has: What is this? Where did it come from? Is it alive? Can I reach it? What’s it called? Together, they form a complete, at-a-glance summary of your container landscape.
3Running Containers vs All Containers
One of the most important distinctions beginners overlook when first learning this command.
By default, this command only shows containers that are currently in a running state. Stopped, exited, or crashed containers are hidden from the default view entirely — even though they still exist on the system and still occupy disk space. This default behavior can genuinely mislead a beginner into thinking a container has disappeared completely, when it has actually just stopped and is sitting quietly, waiting.
A container that crashed moments after starting won’t show up in the default listing at all, making it look as though nothing was ever created. Seeing the complete picture — including stopped containers — requires explicitly asking for “all” containers, not just the running ones.
| View | What It Shows | When To Use It |
|---|---|---|
| Default view | Only containers currently running | Quick check of what’s active right now |
| “All containers” view | Running, stopped, exited, and crashed containers | Investigating what happened to something that disappeared |
4How the Listing Is Produced Internally
A look at what actually happens the moment this command is used.
flowchart TD
A[Request Container Listing] --> B[Docker Engine Consults Its Container Registry]
B --> C{Was 'show all' requested?}
C -- No --> D[Filter To Only Running Containers]
C -- Yes --> E[Include Running, Stopped, and Exited Containers]
D --> F[Format Results Into a Readable Table]
E --> F
F --> G[Display Table: ID, Image, Status, Ports, Names]
The Docker Engine maintains a constantly updated internal record of every container it has ever created on that host — its identity, its current state, and its configuration. This command doesn’t create or discover anything new; it simply reads from that existing record and presents it in a clean, tabular format, applying whatever filters you’ve asked for along the way.
5Understanding the Status Column Deeply
The single most information-dense column in the entire listing.
Up
The container is currently running, along with how long it has been running continuously since it last started.
Exited
The container’s main process has finished or been stopped, along with an exit code that can hint at whether it stopped cleanly or crashed.
Paused
The container’s processes are temporarily frozen in place — still present in memory, but not actively executing until resumed.
Restarting
The container is in the process of being automatically restarted, typically because a restart policy was configured to recover from failures.
An exit code of zero generally signals the process finished cleanly and intentionally, while a non-zero exit code is a strong hint that something went wrong and is worth investigating further.
6Filtering and Narrowing the Output
On a busy machine with dozens of containers, seeing everything at once quickly becomes overwhelming.
As the number of containers on a system grows, scrolling through a long, unfiltered listing becomes tedious and error-prone. Because of this, the listing supports narrowing results down based on specific criteria — such as only showing containers with a particular status, only ones based on a specific image, or only ones matching a particular name pattern. This turns a long wall of information into a focused, targeted answer to a specific question.
Filtering by Status
Useful when you specifically want to investigate everything that has exited recently, separate from what’s currently healthy and running.
Filtering by Name Pattern
Useful when several related containers share a naming convention, letting you view just that group without noise from unrelated containers.
Customizing Displayed Columns
Useful when you only care about specific pieces of information, such as just the names and statuses, without the full default set of columns cluttering the view.
7How This Fits Into a Typical Workflow
Seeing where this command naturally sits among the other everyday Docker actions.
Launch a Container
A new container is started from an image, beginning its life.
Check That It’s Actually Running
The listing command is used immediately afterward to confirm the container is genuinely up and healthy, rather than assuming it worked.
Identify It for Further Commands
The container’s ID or name, seen in the listing, is copied and used as the target for follow-up actions like viewing logs or stopping it.
Periodically Re-check During Development
As work continues, the listing is checked again and again — becoming a habitual, almost reflexive first step whenever something seems off.
Investigate Anything Unexpectedly Missing
If an expected container isn’t showing in the default view, the “all containers” view is used to check whether it stopped or crashed.
8Advantages, Disadvantages, and Trade-offs
Why this simple listing command earns such a central place in everyday Docker use.
Advantages
- Gives an instant, accurate snapshot of the current state of the system
- Completely safe to run at any time — it never modifies anything
- Provides everything needed to identify a container for follow-up commands
- Supports filtering, so it scales gracefully from one container to hundreds
- Works identically regardless of what kind of application the containers are running
Disadvantages / Trade-offs
- Hides stopped containers by default, which can confuse beginners who forget to ask for “all”
- Only reports what Docker itself is tracking — it says nothing about what’s happening inside the application logic of a container
- On a machine with a very large number of containers, the default output can still become hard to read without deliberate filtering
- Doesn’t show real-time resource usage such as CPU or memory by default — that requires a separate, dedicated command
9Best Practices and Common Mistakes
Habits that make this everyday command far more useful.
Make checking the container listing an automatic first step whenever something seems wrong, before assuming the problem lies deeper in the application itself. Half of debugging is confirming the container is even in the state you expect.
Concluding that a container “never started” or “disappeared” just because it doesn’t show up in the default view, without checking the full listing that includes stopped and exited containers.
Ignoring the exit code shown for stopped containers, missing an early signal that something crashed rather than shutting down cleanly.
Use meaningful container names from the start, so the listing itself becomes self-explanatory at a glance, rather than a wall of randomly generated identifiers you have to decode one by one.
10Design Patterns and Anti-Patterns
Recognized right ways and wrong ways to rely on this command in real workflows.
Problem
Relying purely on memory to keep track of which containers are running, instead of routinely checking the actual listing.
Why It’s Harmful
Containers can crash, get automatically restarted, or be left running unnoticed, and memory alone quickly diverges from the real state of the system, leading to confusion and wasted debugging time.
Correct Approach
Treat the listing command as the single source of truth for what’s actually running, and check it directly whenever there’s any doubt, rather than trusting assumptions.
Problem
A team needs a quick, reliable way to confirm deployments succeeded and services are actually up after a release.
Why It’s Harmful
N/A — this describes the recommended solution rather than a problem to avoid.
Correct Approach
Include a listing check as a standard, automated step right after deployment, confirming that expected containers show a healthy running status before considering the release complete.
11Monitoring and Broader Observability
Where this command sits within the larger picture of understanding a running system.
This command answers “what exists and what state is it in,” but it’s just one piece of a complete observability picture. Real resource consumption, detailed logs, and deep internal health checks all come from other dedicated tools. Experienced engineers treat the container listing as the starting point — the first quick glance — before drilling deeper with more specialized commands when something needs closer investigation.
12Security Considerations
Even a simple listing command has security-relevant implications worth understanding.
Information Exposure
Anyone with permission to run this command on a host can see every container running there, including ones belonging to other applications or teams sharing that machine.
Who Can Run It
Since it reads directly from the Docker Engine, the ability to run it typically requires the same level of host access needed to manage containers at all, which is itself a meaningful level of trust.
Exposed Ports Column
The ports column directly reveals what network access points exist on a host, making the listing a useful — and sometimes sensitive — quick audit of a system’s exposed surface.
13Real-World and Industry Examples
How this everyday command shows up across real engineering situations.
Daily Local Development
Developers running several services locally — a database, a cache, an API — routinely check the listing first thing each morning to confirm everything they rely on is still up before starting work.
Post-Deployment Verification
Immediately after deploying a new version of an application, teams check the listing to confirm the new container is running with the expected image and status before declaring the release successful.
Incident Response
When an application seems unreachable, checking the listing is often the very first diagnostic step, quickly answering whether the container is even alive before investigating anything deeper.
Cleanup and Housekeeping
Reviewing the full listing, including stopped containers, helps identify old, forgotten containers that are safe to remove, freeing up disk space and reducing clutter.
14Frequently Asked Questions
No — by default, it only reports containers managed by the Docker Engine on the local machine you’re running it from. Containers on a different host are entirely invisible to it unless you’re specifically connected to that remote Docker Engine.
Because the default view only shows running containers. A container that has stopped still exists and will appear if you explicitly ask to see all containers rather than just the running ones.
Not by default — this listing focuses on identity and status. Live resource usage is reported by a separate, dedicated monitoring command designed specifically for that purpose.
No — container names must be unique on a given host. If you try to reuse a name that’s already taken by an existing container, Docker will refuse and ask you to choose a different one, or remove the conflicting container first.
No — it’s an extremely lightweight operation, since it’s simply reading existing metadata that Docker already tracks internally. It has no meaningful performance impact on the host or on any running containers.
15Summary and Key Takeaways
docker ps is the everyday window into what’s actually happening across your Docker environment — a safe, read-only snapshot of every container’s identity, origin, health, and network exposure. Its default behavior of hiding stopped containers is the single most important nuance for beginners to internalize, since it’s the source of the most common early confusion. Once that distinction clicks, this command becomes second nature: the first thing you check when something feels off, the way a doctor checks a patient’s vital signs before investigating anything more specific.
Key Takeaways
- It’s a read-only status report — running it never changes anything about any container.
- By default, only running containers are shown — stopped and exited ones require explicitly asking for the full, “all containers” view.
- Each row summarizes a container’s full identity — its ID, image, status, ports, and name, all in one glance.
- The status column is the most valuable signal — distinguishing running, exited, paused, and restarting containers, along with exit codes for stopped ones.
- Filtering keeps the output manageable — narrowing results by status, name, or image on busy systems with many containers.
- It’s usually the first diagnostic step — confirming a container’s actual state before investigating deeper into logs or application behavior.
- It complements, but doesn’t replace, deeper monitoring — resource usage and detailed logs come from other, more specialized tools.